@intentsolutionsio/supabase-pack 1.0.0

package/skills/supabase-performance-tuning/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: supabase-performance-tuning
+description: |
+  Optimize Supabase API performance with caching, batching, and connection pooling.
+  Use when experiencing slow API responses, implementing caching strategies,
+  or optimizing request throughput for Supabase integrations.
+  Trigger with phrases like "supabase performance", "optimize supabase",
+  "supabase latency", "supabase caching", "supabase slow", "supabase batch".
+allowed-tools: Read, Write, Edit
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Performance Tuning
+
+## Overview
+Optimize Supabase API performance with caching, batching, and connection pooling.
+
+## Prerequisites
+- Supabase SDK installed
+- Understanding of async patterns
+- Redis or in-memory cache available (optional)
+- Performance monitoring in place
+
+## Latency Benchmarks
+
+| Operation | P50 | P95 | P99 |
+|-----------|-----|-----|-----|
+| Select | 15ms | 50ms | 100ms |
+| Insert | 25ms | 75ms | 150ms |
+| Real-time Subscribe | 50ms | 150ms | 300ms |
+
+## Caching Strategy
+
+### Response Caching
+```typescript
+import { LRUCache } from 'lru-cache';
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 30000, // 1 minute
+  updateAgeOnGet: true,
+});
+
+async function cachedSupabaseRequest<T>(
+  key: string,
+  fetcher: () => Promise<T>,
+  ttl?: number
+): Promise<T> {
+  const cached = cache.get(key);
+  if (cached) return cached as T;
+
+  const result = await fetcher();
+  cache.set(key, result, { ttl });
+  return result;
+}
+```
+
+### Redis Caching (Distributed)
+```typescript
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+async function cachedWithRedis<T>(
+  key: string,
+  fetcher: () => Promise<T>,
+  ttlSeconds = 60
+): Promise<T> {
+  const cached = await redis.get(key);
+  if (cached) return JSON.parse(cached);
+
+  const result = await fetcher();
+  await redis.setex(key, ttlSeconds, JSON.stringify(result));
+  return result;
+}
+```
+
+## Request Batching
+
+```typescript
+import DataLoader from 'dataloader';
+
+const supabaseLoader = new DataLoader<string, any>(
+  async (ids) => {
+    // Batch fetch from Supabase
+    const results = await supabaseClient.batchGet(ids);
+    return ids.map(id => results.find(r => r.id === id) || null);
+  },
+  {
+    maxBatchSize: 100,
+    batchScheduleFn: callback => setTimeout(callback, 10),
+  }
+);
+
+// Usage - automatically batched
+const [item1, item2, item3] = await Promise.all([
+  supabaseLoader.load('id-1'),
+  supabaseLoader.load('id-2'),
+  supabaseLoader.load('id-3'),
+]);
+```
+
+## Connection Optimization
+
+```typescript
+import { Agent } from 'https';
+
+// Keep-alive connection pooling
+const agent = new Agent({
+  keepAlive: true,
+  maxSockets: 15,
+  maxFreeSockets: 5,
+  timeout: 30000,
+});
+
+const client = new SupabaseClient({
+  apiKey: process.env.SUPABASE_API_KEY!,
+  httpAgent: agent,
+});
+```
+
+## Pagination Optimization
+
+```typescript
+async function* paginatedSupabaseList<T>(
+  fetcher: (cursor?: string) => Promise<{ data: T[]; nextCursor?: string }>
+): AsyncGenerator<T> {
+  let cursor: string | undefined;
+
+  do {
+    const { data, nextCursor } = await fetcher(cursor);
+    for (const item of data) {
+      yield item;
+    }
+    cursor = nextCursor;
+  } while (cursor);
+}
+
+// Usage
+for await (const item of paginatedSupabaseList(cursor =>
+  supabaseClient.list({ cursor, limit: 100 })
+)) {
+  await process(item);
+}
+```
+
+## Performance Monitoring
+
+```typescript
+async function measuredSupabaseCall<T>(
+  operation: string,
+  fn: () => Promise<T>
+): Promise<T> {
+  const start = performance.now();
+  try {
+    const result = await fn();
+    const duration = performance.now() - start;
+    console.log({ operation, duration, status: 'success' });
+    return result;
+  } catch (error) {
+    const duration = performance.now() - start;
+    console.error({ operation, duration, status: 'error', error });
+    throw error;
+  }
+}
+```
+
+## Instructions
+
+### Step 1: Establish Baseline
+Measure current latency for critical Supabase operations.
+
+### Step 2: Implement Caching
+Add response caching for frequently accessed data.
+
+### Step 3: Enable Batching
+Use DataLoader or similar for automatic request batching.
+
+### Step 4: Optimize Connections
+Configure connection pooling with keep-alive.
+
+## Output
+- Reduced API latency
+- Caching layer implemented
+- Request batching enabled
+- Connection pooling configured
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Cache miss storm | TTL expired | Use stale-while-revalidate |
+| Batch timeout | Too many items | Reduce batch size |
+| Connection exhausted | No pooling | Configure max sockets |
+| Memory pressure | Cache too large | Set max cache entries |
+
+## Examples
+
+### Quick Performance Wrapper
+```typescript
+const withPerformance = <T>(name: string, fn: () => Promise<T>) =>
+  measuredSupabaseCall(name, () =>
+    cachedSupabaseRequest(`cache:${name}`, fn)
+  );
+```
+
+## Resources
+- [Supabase Performance Guide](https://supabase.com/docs/performance)
+- [DataLoader Documentation](https://github.com/graphql/dataloader)
+- [LRU Cache Documentation](https://github.com/isaacs/node-lru-cache)
+
+## Next Steps
+For cost optimization, see `supabase-cost-tuning`.

package/skills/supabase-policy-guardrails/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: supabase-policy-guardrails
+description: |
+  Implement Supabase lint rules, policy enforcement, and automated guardrails.
+  Use when setting up code quality rules for Supabase integrations, implementing
+  pre-commit hooks, or configuring CI policy checks for Supabase best practices.
+  Trigger with phrases like "supabase policy", "supabase lint",
+  "supabase guardrails", "supabase best practices check", "supabase eslint".
+allowed-tools: Read, Write, Edit, Bash(npx:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Policy & Guardrails
+
+## Overview
+Automated policy enforcement and guardrails for Supabase integrations.
+
+## Prerequisites
+- ESLint configured in project
+- Pre-commit hooks infrastructure
+- CI/CD pipeline with policy checks
+- TypeScript for type enforcement
+
+## ESLint Rules
+
+### Custom Supabase Plugin
+```javascript
+// eslint-plugin-supabase/rules/no-hardcoded-keys.js
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow hardcoded Supabase API keys',
+    },
+    fixable: 'code',
+  },
+  create(context) {
+    return {
+      Literal(node) {
+        if (typeof node.value === 'string') {
+          if (node.value.match(/^sk_(live|test)_[a-zA-Z0-9]{24,}/)) {
+            context.report({
+              node,
+              message: 'Hardcoded Supabase API key detected',
+            });
+          }
+        }
+      },
+    };
+  },
+};
+```
+
+### ESLint Configuration
+```javascript
+// .eslintrc.js
+module.exports = {
+  plugins: ['supabase'],
+  rules: {
+    'supabase/no-hardcoded-keys': 'error',
+    'supabase/require-error-handling': 'warn',
+    'supabase/use-typed-client': 'warn',
+  },
+};
+```
+
+## Pre-Commit Hooks
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: supabase-secrets-check
+        name: Check for Supabase secrets
+        entry: bash -c 'git diff --cached --name-only | xargs grep -l "sk_live_" && exit 1 || exit 0'
+        language: system
+        pass_filenames: false
+
+      - id: supabase-config-validate
+        name: Validate Supabase configuration
+        entry: node scripts/validate-supabase-config.js
+        language: node
+        files: '\.supabase\.json$'
+```
+
+## TypeScript Strict Patterns
+
+```typescript
+// Enforce typed configuration
+interface SupabaseStrictConfig {
+  apiKey: string;  // Required
+  environment: 'development' | 'staging' | 'production';  // Enum
+  timeout: number;  // Required number, not optional
+  retries: number;
+}
+
+// Disallow any in Supabase code
+// @ts-expect-error - Using any is forbidden
+const client = new Client({ apiKey: any });
+
+// Prefer this
+const client = new SupabaseClient(config satisfies SupabaseStrictConfig);
+```
+
+## Architecture Decision Records
+
+### ADR Template
+```markdown
+# ADR-001: Supabase Client Initialization
+
+## Status
+Accepted
+
+## Context
+We need to decide how to initialize the Supabase client across our application.
+
+## Decision
+We will use the singleton pattern with lazy initialization.
+
+## Consequences
+- Pro: Single client instance, connection reuse
+- Pro: Easy to mock in tests
+- Con: Global state requires careful lifecycle management
+
+## Enforcement
+- ESLint rule: supabase/use-singleton-client
+- CI check: grep for "new SupabaseClient(" outside allowed files
+```
+
+## Policy-as-Code (OPA)
+
+```rego
+# supabase-policy.rego
+package supabase
+
+# Deny production API keys in non-production environments
+deny[msg] {
+  input.environment != "production"
+  startswith(input.apiKey, "sk_live_")
+  msg := "Production API keys not allowed in non-production environment"
+}
+
+# Require minimum timeout
+deny[msg] {
+  input.timeout < 10000
+  msg := sprintf("Timeout too low: %d < 10000ms minimum", [input.timeout])
+}
+
+# Require retry configuration
+deny[msg] {
+  not input.retries
+  msg := "Retry configuration is required"
+}
+```
+
+## CI Policy Checks
+
+```yaml
+# .github/workflows/supabase-policy.yml
+name: Supabase Policy Check
+
+on: [push, pull_request]
+
+jobs:
+  policy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check for hardcoded secrets
+        run: |
+          if grep -rE "sk_(live|test)_[a-zA-Z0-9]{24,}" --include="*.ts" --include="*.js" .; then
+            echo "ERROR: Hardcoded Supabase keys found"
+            exit 1
+          fi
+
+      - name: Validate configuration schema
+        run: |
+          npx ajv validate -s supabase-config.schema.json -d config/supabase/*.json
+
+      - name: Run ESLint Supabase rules
+        run: npx eslint --plugin supabase --rule 'supabase/no-hardcoded-keys: error' src/
+```
+
+## Runtime Guardrails
+
+```typescript
+// Prevent dangerous operations in production
+const BLOCKED_IN_PROD = ['deleteAll', 'resetData', 'migrateDown'];
+
+function guardSupabaseOperation(operation: string): void {
+  const isProd = process.env.NODE_ENV === 'production';
+
+  if (isProd && BLOCKED_IN_PROD.includes(operation)) {
+    throw new Error(`Operation '${operation}' blocked in production`);
+  }
+}
+
+// Rate limit protection
+function guardRateLimits(requestsInWindow: number): void {
+  const limit = parseInt(process.env.SUPABASE_RATE_LIMIT || '100');
+
+  if (requestsInWindow > limit * 0.9) {
+    console.warn('Approaching Supabase rate limit');
+  }
+
+  if (requestsInWindow >= limit) {
+    throw new Error('Supabase rate limit exceeded - request blocked');
+  }
+}
+```
+
+## Instructions
+
+### Step 1: Create ESLint Rules
+Implement custom lint rules for Supabase patterns.
+
+### Step 2: Configure Pre-Commit Hooks
+Set up hooks to catch issues before commit.
+
+### Step 3: Add CI Policy Checks
+Implement policy-as-code in CI pipeline.
+
+### Step 4: Enable Runtime Guardrails
+Add production safeguards for dangerous operations.
+
+## Output
+- ESLint plugin with Supabase rules
+- Pre-commit hooks blocking secrets
+- CI policy checks passing
+- Runtime guardrails active
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| ESLint rule not firing | Wrong config | Check plugin registration |
+| Pre-commit skipped | --no-verify | Enforce in CI |
+| Policy false positive | Regex too broad | Narrow pattern match |
+| Guardrail triggered | Actual issue | Fix or whitelist |
+
+## Examples
+
+### Quick ESLint Check
+```bash
+npx eslint --plugin supabase --rule 'supabase/no-hardcoded-keys: error' src/
+```
+
+## Resources
+- [ESLint Plugin Development](https://eslint.org/docs/latest/extend/plugins)
+- [Pre-commit Framework](https://pre-commit.com/)
+- [Open Policy Agent](https://www.openpolicyagent.org/)
+
+## Next Steps
+For architecture blueprints, see `supabase-architecture-variants`.

package/skills/supabase-prod-checklist/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: supabase-prod-checklist
+description: |
+  Execute Supabase production deployment checklist and rollback procedures.
+  Use when deploying Supabase integrations to production, preparing for launch,
+  or implementing go-live procedures.
+  Trigger with phrases like "supabase production", "deploy supabase",
+  "supabase go-live", "supabase launch checklist".
+allowed-tools: Read, Bash(kubectl:*), Bash(curl:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Production Checklist
+
+## Overview
+Complete checklist for deploying Supabase integrations to production.
+
+## Prerequisites
+- Staging environment tested and verified
+- Production API keys available
+- Deployment pipeline configured
+- Monitoring and alerting ready
+
+## Instructions
+
+### Step 1: Pre-Deployment Configuration
+- [ ] Production API keys in secure vault
+- [ ] Environment variables set in deployment platform
+- [ ] API key scopes are minimal (least privilege)
+- [ ] Webhook endpoints configured with HTTPS
+- [ ] Webhook secrets stored securely
+
+### Step 2: Code Quality Verification
+- [ ] All tests passing (`npm test`)
+- [ ] No hardcoded credentials
+- [ ] Error handling covers all Supabase error types
+- [ ] Rate limiting/backoff implemented
+- [ ] Logging is production-appropriate
+
+### Step 3: Infrastructure Setup
+- [ ] Health check endpoint includes Supabase connectivity
+- [ ] Monitoring/alerting configured
+- [ ] Circuit breaker pattern implemented
+- [ ] Graceful degradation configured
+
+### Step 4: Documentation Requirements
+- [ ] Incident runbook created
+- [ ] Key rotation procedure documented
+- [ ] Rollback procedure documented
+- [ ] On-call escalation path defined
+
+### Step 5: Deploy with Gradual Rollout
+```bash
+# Pre-flight checks
+curl -f https://staging.example.com/health
+curl -s https://status.supabase.com
+
+# Gradual rollout - start with canary (10%)
+kubectl apply -f k8s/production.yaml
+kubectl set image deployment/supabase-integration app=image:new --record
+kubectl rollout pause deployment/supabase-integration
+
+# Monitor canary traffic for 10 minutes
+sleep 600
+# Check error rates and latency before continuing
+
+# If healthy, continue rollout to 50%
+kubectl rollout resume deployment/supabase-integration
+kubectl rollout pause deployment/supabase-integration
+sleep 300
+
+# Complete rollout to 100%
+kubectl rollout resume deployment/supabase-integration
+kubectl rollout status deployment/supabase-integration
+```
+
+## Output
+- Deployed Supabase integration
+- Health checks passing
+- Monitoring active
+- Rollback procedure documented
+
+## Error Handling
+| Alert | Condition | Severity |
+|-------|-----------|----------|
+| API Down | 5xx errors > 10/min | P1 |
+| High Latency | p99 > 5000ms | P2 |
+| Rate Limited | 429 errors > 5/min | P2 |
+| Auth Failures | 401/403 errors > 0 | P1 |
+
+## Examples
+
+### Health Check Implementation
+```typescript
+async function healthCheck(): Promise<{ status: string; supabase: any }> {
+  const start = Date.now();
+  try {
+    await supabaseClient.ping();
+    return { status: 'healthy', supabase: { connected: true, latencyMs: Date.now() - start } };
+  } catch (error) {
+    return { status: 'degraded', supabase: { connected: false, latencyMs: Date.now() - start } };
+  }
+}
+```
+
+### Immediate Rollback
+```bash
+kubectl rollout undo deployment/supabase-integration
+kubectl rollout status deployment/supabase-integration
+```
+
+## Resources
+- [Supabase Status](https://status.supabase.com)
+- [Supabase Support](https://supabase.com/docs/support)
+
+## Next Steps
+For version upgrades, see `supabase-upgrade-migration`.