@intentsolutionsio/supabase-pack 1.0.0

package/skills/supabase-known-pitfalls/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: supabase-known-pitfalls
+description: |
+  Identify and avoid Supabase anti-patterns and common integration mistakes.
+  Use when reviewing Supabase code for issues, onboarding new developers,
+  or auditing existing Supabase integrations for best practices violations.
+  Trigger with phrases like "supabase mistakes", "supabase anti-patterns",
+  "supabase pitfalls", "supabase what not to do", "supabase code review".
+allowed-tools: Read, Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Known Pitfalls
+
+## Overview
+Common mistakes and anti-patterns when integrating with Supabase.
+
+## Prerequisites
+- Access to Supabase codebase for review
+- Understanding of async/await patterns
+- Knowledge of security best practices
+- Familiarity with rate limiting concepts
+
+## Pitfall #1: Synchronous API Calls in Request Path
+
+### ❌ Anti-Pattern
+```typescript
+// User waits for Supabase API call
+app.post('/checkout', async (req, res) => {
+  const payment = await supabaseClient.processPayment(req.body);  // 2-5s latency
+  const notification = await supabaseClient.sendEmail(payment);   // Another 1-2s
+  res.json({ success: true });  // User waited 3-7s
+});
+```
+
+### ✅ Better Approach
+```typescript
+// Return immediately, process async
+app.post('/checkout', async (req, res) => {
+  const jobId = await queue.enqueue('process-checkout', req.body);
+  res.json({ jobId, status: 'processing' });  // 50ms response
+});
+
+// Background job
+async function processCheckout(data) {
+  const payment = await supabaseClient.processPayment(data);
+  await supabaseClient.sendEmail(payment);
+}
+```
+
+---
+
+## Pitfall #2: Not Handling Rate Limits
+
+### ❌ Anti-Pattern
+```typescript
+// Blast requests, crash on 429
+for (const item of items) {
+  await supabaseClient.process(item);  // Will hit rate limit
+}
+```
+
+### ✅ Better Approach
+```typescript
+import pLimit from 'p-limit';
+
+const limit = pLimit(5);  // Max 5 concurrent
+const rateLimiter = new RateLimiter({ tokensPerSecond: 10 });
+
+for (const item of items) {
+  await rateLimiter.acquire();
+  await limit(() => supabaseClient.process(item));
+}
+```
+
+---
+
+## Pitfall #3: Leaking API Keys
+
+### ❌ Anti-Pattern
+```typescript
+// In frontend code (visible to users!)
+const client = new SupabaseClient({
+  apiKey: 'sk_live_ACTUAL_KEY_HERE',  // Anyone can see this
+});
+
+// In git history
+git commit -m "add API key"  // Exposed forever
+```
+
+### ✅ Better Approach
+```typescript
+// Backend only, environment variable
+const client = new SupabaseClient({
+  apiKey: process.env.SUPABASE_API_KEY,
+});
+
+// Use .gitignore
+.env
+.env.local
+.env.*.local
+```
+
+---
+
+## Pitfall #4: Ignoring Idempotency
+
+### ❌ Anti-Pattern
+```typescript
+// Network error on response = duplicate charge!
+try {
+  await supabaseClient.charge(order);
+} catch (error) {
+  if (error.code === 'NETWORK_ERROR') {
+    await supabaseClient.charge(order);  // Charged twice!
+  }
+}
+```
+
+### ✅ Better Approach
+```typescript
+const idempotencyKey = `order-${order.id}-${Date.now()}`;
+
+await supabaseClient.charge(order, {
+  idempotencyKey,  // Safe to retry
+});
+```
+
+---
+
+## Pitfall #5: Not Validating Webhooks
+
+### ❌ Anti-Pattern
+```typescript
+// Trust any incoming request
+app.post('/webhook', (req, res) => {
+  processWebhook(req.body);  // Attacker can send fake events
+  res.sendStatus(200);
+});
+```
+
+### ✅ Better Approach
+```typescript
+app.post('/webhook',
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    const signature = req.headers['x-supabase-signature'];
+    if (!verifySupabaseSignature(req.body, signature)) {
+      return res.sendStatus(401);
+    }
+    processWebhook(JSON.parse(req.body));
+    res.sendStatus(200);
+  }
+);
+```
+
+---
+
+## Pitfall #6: Missing Error Handling
+
+### ❌ Anti-Pattern
+```typescript
+// Crashes on any error
+const result = await supabaseClient.get(id);
+console.log(result.data.nested.value);  // TypeError if missing
+```
+
+### ✅ Better Approach
+```typescript
+try {
+  const result = await supabaseClient.get(id);
+  console.log(result?.data?.nested?.value ?? 'default');
+} catch (error) {
+  if (error instanceof SupabaseNotFoundError) {
+    return null;
+  }
+  if (error instanceof SupabaseRateLimitError) {
+    await sleep(error.retryAfter);
+    return this.get(id);  // Retry
+  }
+  throw error;  // Rethrow unknown errors
+}
+```
+
+---
+
+## Pitfall #7: Hardcoding Configuration
+
+### ❌ Anti-Pattern
+```typescript
+const client = new SupabaseClient({
+  timeout: 5000,  // Too short for some operations
+  baseUrl: 'https://api.supabase.com',  // Can't change for staging
+});
+```
+
+### ✅ Better Approach
+```typescript
+const client = new SupabaseClient({
+  timeout: parseInt(process.env.SUPABASE_TIMEOUT || '30000'),
+  baseUrl: process.env.SUPABASE_BASE_URL || 'https://api.supabase.com',
+});
+```
+
+---
+
+## Pitfall #8: Not Implementing Circuit Breaker
+
+### ❌ Anti-Pattern
+```typescript
+// When Supabase is down, every request hangs
+for (const user of users) {
+  await supabaseClient.sync(user);  // All timeout sequentially
+}
+```
+
+### ✅ Better Approach
+```typescript
+import CircuitBreaker from 'opossum';
+
+const breaker = new CircuitBreaker(supabaseClient.sync, {
+  timeout: 10000,
+  errorThresholdPercentage: 50,
+  resetTimeout: 30000,
+});
+
+// Fails fast when circuit is open
+for (const user of users) {
+  await breaker.fire(user).catch(handleFailure);
+}
+```
+
+---
+
+## Pitfall #9: Logging Sensitive Data
+
+### ❌ Anti-Pattern
+```typescript
+console.log('Request:', JSON.stringify(request));  // Logs API key, PII
+console.log('User:', user);  // Logs email, phone
+```
+
+### ✅ Better Approach
+```typescript
+const redacted = {
+  ...request,
+  apiKey: '[REDACTED]',
+  user: { id: user.id },  // Only non-sensitive fields
+};
+console.log('Request:', JSON.stringify(redacted));
+```
+
+---
+
+## Pitfall #10: No Graceful Degradation
+
+### ❌ Anti-Pattern
+```typescript
+// Entire feature broken if Supabase is down
+const recommendations = await supabaseClient.getRecommendations(userId);
+return renderPage({ recommendations });  // Page crashes
+```
+
+### ✅ Better Approach
+```typescript
+let recommendations;
+try {
+  recommendations = await supabaseClient.getRecommendations(userId);
+} catch (error) {
+  recommendations = await getFallbackRecommendations(userId);
+  reportDegradedService('supabase', error);
+}
+return renderPage({ recommendations, degraded: !recommendations });
+```
+
+---
+
+## Instructions
+
+### Step 1: Review for Anti-Patterns
+Scan codebase for each pitfall pattern.
+
+### Step 2: Prioritize Fixes
+Address security issues first, then performance.
+
+### Step 3: Implement Better Approach
+Replace anti-patterns with recommended patterns.
+
+### Step 4: Add Prevention
+Set up linting and CI checks to prevent recurrence.
+
+## Output
+- Anti-patterns identified
+- Fixes prioritized and implemented
+- Prevention measures in place
+- Code quality improved
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Too many findings | Legacy codebase | Prioritize security first |
+| Pattern not detected | Complex code | Manual review |
+| False positive | Similar code | Whitelist exceptions |
+| Fix breaks tests | Behavior change | Update tests |
+
+## Examples
+
+### Quick Pitfall Scan
+```bash
+# Check for common pitfalls
+grep -r "sk_live_" --include="*.ts" src/        # Key leakage
+grep -r "console.log" --include="*.ts" src/     # Potential PII logging
+```
+
+## Resources
+- [Supabase Security Guide](https://supabase.com/docs/security)
+- [Supabase Best Practices](https://supabase.com/docs/best-practices)
+
+## Quick Reference Card
+
+| Pitfall | Detection | Prevention |
+|---------|-----------|------------|
+| Sync in request | High latency | Use queues |
+| Rate limit ignore | 429 errors | Implement backoff |
+| Key leakage | Git history scan | Env vars, .gitignore |
+| No idempotency | Duplicate records | Idempotency keys |
+| Unverified webhooks | Security audit | Signature verification |
+| Missing error handling | Crashes | Try-catch, types |
+| Hardcoded config | Code review | Environment variables |
+| No circuit breaker | Cascading failures | opossum, resilience4j |
+| Logging PII | Log audit | Redaction middleware |
+| No degradation | Total outages | Fallback systems |

package/skills/supabase-load-scale/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: supabase-load-scale
+description: |
+  Implement Supabase load testing, auto-scaling, and capacity planning strategies.
+  Use when running performance tests, configuring horizontal scaling,
+  or planning capacity for Supabase integrations.
+  Trigger with phrases like "supabase load test", "supabase scale",
+  "supabase performance test", "supabase capacity", "supabase k6", "supabase benchmark".
+allowed-tools: Read, Write, Edit, Bash(k6:*), Bash(kubectl:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Load & Scale
+
+## Overview
+Load testing, scaling strategies, and capacity planning for Supabase integrations.
+
+## Prerequisites
+- k6 load testing tool installed
+- Kubernetes cluster with HPA configured
+- Prometheus for metrics collection
+- Test environment API keys
+
+## Load Testing with k6
+
+### Basic Load Test
+```javascript
+// supabase-load-test.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '2m', target: 10 },   // Ramp up
+    { duration: '5m', target: 10 },   // Steady state
+    { duration: '2m', target: 50 },   // Ramp to peak
+    { duration: '5m', target: 50 },   // Stress test
+    { duration: '2m', target: 0 },    // Ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<200'],
+    http_req_failed: ['rate<0.01'],
+  },
+};
+
+export default function () {
+  const response = http.post(
+    'https://api.supabase.com/v1/resource',
+    JSON.stringify({ test: true }),
+    {
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${__ENV.SUPABASE_API_KEY}`,
+      },
+    }
+  );
+
+  check(response, {
+    'status is 200': (r) => r.status === 200,
+    'latency < 200ms': (r) => r.timings.duration < 200,
+  });
+
+  sleep(1);
+}
+```
+
+### Run Load Test
+```bash
+# Install k6
+brew install k6  # macOS
+# or: sudo apt install k6  # Linux
+
+# Run test
+k6 run --env SUPABASE_API_KEY=${SUPABASE_API_KEY} supabase-load-test.js
+
+# Run with output to InfluxDB
+k6 run --out influxdb=http://localhost:8086/k6 supabase-load-test.js
+```
+
+## Scaling Patterns
+
+### Horizontal Scaling
+```yaml
+# kubernetes HPA
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: supabase-integration-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: supabase-integration
+  minReplicas: 2
+  maxReplicas: 20
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+    - type: Pods
+      pods:
+        metric:
+          name: supabase_queue_depth
+        target:
+          type: AverageValue
+          averageValue: 100
+```
+
+### Connection Pooling
+```typescript
+import { Pool } from 'generic-pool';
+
+const supabasePool = Pool.create({
+  create: async () => {
+    return new SupabaseClient({
+      apiKey: process.env.SUPABASE_API_KEY!,
+    });
+  },
+  destroy: async (client) => {
+    await client.close();
+  },
+  max: 20,
+  min: 5,
+  idleTimeoutMillis: 30000,
+});
+
+async function withSupabaseClient<T>(
+  fn: (client: SupabaseClient) => Promise<T>
+): Promise<T> {
+  const client = await supabasePool.acquire();
+  try {
+    return await fn(client);
+  } finally {
+    supabasePool.release(client);
+  }
+}
+```
+
+## Capacity Planning
+
+### Metrics to Monitor
+| Metric | Warning | Critical |
+|--------|---------|----------|
+| CPU Utilization | > 70% | > 85% |
+| Memory Usage | > 75% | > 90% |
+| Request Queue Depth | > 100 | > 500 |
+| Error Rate | > 1% | > 5% |
+| P95 Latency | > 500ms | > 2000ms |
+
+### Capacity Calculation
+```typescript
+interface CapacityEstimate {
+  currentRPS: number;
+  maxRPS: number;
+  headroom: number;
+  scaleRecommendation: string;
+}
+
+function estimateSupabaseCapacity(
+  metrics: SystemMetrics
+): CapacityEstimate {
+  const currentRPS = metrics.requestsPerSecond;
+  const avgLatency = metrics.p50Latency;
+  const cpuUtilization = metrics.cpuPercent;
+
+  // Estimate max RPS based on current performance
+  const maxRPS = currentRPS / (cpuUtilization / 100) * 0.7; // 70% target
+  const headroom = ((maxRPS - currentRPS) / currentRPS) * 100;
+
+  return {
+    currentRPS,
+    maxRPS: Math.floor(maxRPS),
+    headroom: Math.round(headroom),
+    scaleRecommendation: headroom < 30
+      ? 'Scale up soon'
+      : headroom < 50
+      ? 'Monitor closely'
+      : 'Adequate capacity',
+  };
+}
+```
+
+## Benchmark Results Template
+
+```markdown
+## Supabase Performance Benchmark
+**Date:** YYYY-MM-DD
+**Environment:** [staging/production]
+**SDK Version:** X.Y.Z
+
+### Test Configuration
+- Duration: 10 minutes
+- Ramp: 10 → 100 → 10 VUs
+- Target endpoint: /v1/resource
+
+### Results
+| Metric | Value |
+|--------|-------|
+| Total Requests | 50,000 |
+| Success Rate | 99.9% |
+| P50 Latency | 120ms |
+| P95 Latency | 350ms |
+| P99 Latency | 800ms |
+| Max RPS Achieved | 150 |
+
+### Observations
+- [Key finding 1]
+- [Key finding 2]
+
+### Recommendations
+- [Scaling recommendation]
+```
+
+## Instructions
+
+### Step 1: Create Load Test Script
+Write k6 test script with appropriate thresholds.
+
+### Step 2: Configure Auto-Scaling
+Set up HPA with CPU and custom metrics.
+
+### Step 3: Run Load Test
+Execute test and collect metrics.
+
+### Step 4: Analyze and Document
+Record results in benchmark template.
+
+## Output
+- Load test script created
+- HPA configured
+- Benchmark results documented
+- Capacity recommendations defined
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| k6 timeout | Rate limited | Reduce RPS |
+| HPA not scaling | Wrong metrics | Verify metric name |
+| Connection refused | Pool exhausted | Increase pool size |
+| Inconsistent results | Warm-up needed | Add ramp-up phase |
+
+## Examples
+
+### Quick k6 Test
+```bash
+k6 run --vus 10 --duration 30s supabase-load-test.js
+```
+
+### Check Current Capacity
+```typescript
+const metrics = await getSystemMetrics();
+const capacity = estimateSupabaseCapacity(metrics);
+console.log('Headroom:', capacity.headroom + '%');
+console.log('Recommendation:', capacity.scaleRecommendation);
+```
+
+### Scale HPA Manually
+```bash
+kubectl scale deployment supabase-integration --replicas=5
+kubectl get hpa supabase-integration-hpa
+```
+
+## Resources
+- [k6 Documentation](https://k6.io/docs/)
+- [Kubernetes HPA](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)
+- [Supabase Rate Limits](https://supabase.com/docs/rate-limits)
+
+## Next Steps
+For reliability patterns, see `supabase-reliability-patterns`.

package/skills/supabase-local-dev-loop/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: supabase-local-dev-loop
+description: |
+  Configure Supabase local development with hot reload and testing.
+  Use when setting up a development environment, configuring test workflows,
+  or establishing a fast iteration cycle with Supabase.
+  Trigger with phrases like "supabase dev setup", "supabase local development",
+  "supabase dev environment", "develop with supabase".
+allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pnpm:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Local Dev Loop
+
+## Overview
+Set up a fast, reproducible local development workflow for Supabase.
+
+## Prerequisites
+- Completed `supabase-install-auth` setup
+- Node.js 18+ with npm/pnpm
+- Code editor with TypeScript support
+- Git for version control
+
+## Instructions
+
+### Step 1: Create Project Structure
+```
+my-supabase-project/
+├── src/
+│   ├── supabase/
+│   │   ├── client.ts       # Supabase client wrapper
+│   │   ├── config.ts       # Configuration management
+│   │   └── utils.ts        # Helper functions
+│   └── index.ts
+├── tests/
+│   └── supabase.test.ts
+├── .env.local              # Local secrets (git-ignored)
+├── .env.example            # Template for team
+└── package.json
+```
+
+### Step 2: Configure Environment
+```bash
+# Copy environment template
+cp .env.example .env.local
+
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+```
+
+### Step 3: Setup Hot Reload
+```json
+{
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "test": "vitest",
+    "test:watch": "vitest --watch"
+  }
+}
+```
+
+### Step 4: Configure Testing
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { SupabaseClient } from '../src/supabase/client';
+
+describe('Supabase Client', () => {
+  it('should initialize with API key', () => {
+    const client = new SupabaseClient({ apiKey: 'test-key' });
+    expect(client).toBeDefined();
+  });
+});
+```
+
+## Output
+- Working development environment with hot reload
+- Configured test suite with mocking
+- Environment variable management
+- Fast iteration cycle for Supabase development
+
+## Error Handling
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Module not found | Missing dependency | Run `npm install` |
+| Port in use | Another process | Kill process or change port |
+| Env not loaded | Missing .env.local | Copy from .env.example |
+| Test timeout | Slow network | Increase test timeout |
+
+## Examples
+
+### Mock Supabase Responses
+```typescript
+vi.mock('@supabase/supabase-js', () => ({
+  SupabaseClient: vi.fn().mockImplementation(() => ({
+    // Mock methods here
+  })),
+}));
+```
+
+### Debug Mode
+```bash
+# Enable verbose logging
+DEBUG=SUPABASE=* npm run dev
+```
+
+## Resources
+- [Supabase SDK Reference](https://supabase.com/docs/sdk)
+- [Vitest Documentation](https://vitest.dev/)
+- [tsx Documentation](https://github.com/esbuild-kit/tsx)
+
+## Next Steps
+See `supabase-sdk-patterns` for production-ready code patterns.