@intentsolutionsio/supabase-pack 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "supabase-pack",
+  "version": "1.0.0",
+  "description": "Claude Code skill pack for Supabase (30 skills)",
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "jeremy@intentsolutions.io"
+  },
+  "license": "MIT",
+  "keywords": [
+    "supabase",
+    "supabase",
+    "saas",
+    "sdk",
+    "integration"
+  ]
+}

package/000-docs/001-BL-LICN-license.txt

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2025 Jeremy Longshore

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jeremy Longshore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# Supabase Skill Pack
+
+> Claude Code skill pack for Supabase integration (30 skills)
+
+## Installation
+
+```bash
+/plugin install supabase-pack@claude-code-plugins-plus
+```
+
+## Skills Included
+
+### Standard Skills (S01-S12)
+| Skill | Description |
+|-------|-------------|
+| `supabase-install-auth` | Install Auth |
+| `supabase-hello-world` | Hello World |
+| `supabase-local-dev-loop` | Local Dev Loop |
+| `supabase-sdk-patterns` | Sdk Patterns |
+| `supabase-schema-from-requirements` | Schema From Requirements |
+| `supabase-auth-storage-realtime-core` | Auth Storage Realtime Core |
+| `supabase-common-errors` | Common Errors |
+| `supabase-debug-bundle` | Debug Bundle |
+| `supabase-rate-limits` | Rate Limits |
+| `supabase-security-basics` | Security Basics |
+| `supabase-prod-checklist` | Prod Checklist |
+| `supabase-upgrade-migration` | Upgrade Migration |
+
+### Pro Skills (P13-P18)
+| Skill | Description |
+|-------|-------------|
+| `supabase-ci-integration` | Ci Integration |
+| `supabase-deploy-integration` | Deploy Integration |
+| `supabase-webhooks-events` | Webhooks Events |
+| `supabase-performance-tuning` | Performance Tuning |
+| `supabase-cost-tuning` | Cost Tuning |
+| `supabase-reference-architecture` | Reference Architecture |
+
+### Flagship Skills (F19-F24)
+| Skill | Description |
+|-------|-------------|
+| `supabase-multi-env-setup` | Multi Env Setup |
+| `supabase-observability` | Observability |
+| `supabase-incident-runbook` | Incident Runbook |
+| `supabase-data-handling` | Data Handling |
+| `supabase-enterprise-rbac` | Enterprise Rbac |
+| `supabase-migration-deep-dive` | Migration Deep Dive |
+
+### Flagship+ Skills (X25-X30)
+| Skill | Description |
+|-------|-------------|
+| `supabase-advanced-troubleshooting` | Advanced Troubleshooting |
+| `supabase-load-scale` | Load Scale |
+| `supabase-reliability-patterns` | Reliability Patterns |
+| `supabase-policy-guardrails` | Policy Guardrails |
+| `supabase-architecture-variants` | Architecture Variants |
+| `supabase-known-pitfalls` | Known Pitfalls |
+
+## Usage
+
+Skills trigger automatically when you discuss Supabase topics. For example:
+
+- "Help me set up Supabase" → triggers `supabase-install-auth`
+- "Debug this Supabase error" → triggers `supabase-common-errors`
+- "Deploy my Supabase integration" → triggers `supabase-deploy-integration`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@intentsolutionsio/supabase-pack",
+  "version": "1.0.0",
+  "description": "Claude Code skill pack for Supabase - 30 skills covering database operations, authentication, edge functions, realtime subscriptions, and production operations",
+  "main": "README.md",
+  "type": "module",
+  "files": [
+    "README.md",
+    "LICENSE",
+    ".claude-plugin/",
+    "skills/",
+    "000-docs/"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "supabase",
+    "database",
+    "postgres",
+    "authentication",
+    "edge-functions",
+    "realtime",
+    "ai-skills",
+    "saas-pack"
+  ],
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "jeremy@intentsolutions.io"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins.git",
+    "directory": "plugins/saas-packs/supabase-pack"
+  },
+  "bugs": {
+    "url": "https://github.com/jeremylongshore/claude-code-plugins/issues"
+  },
+  "homepage": "https://claudecodeplugins.io/plugins/supabase-pack",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/supabase-advanced-troubleshooting/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: supabase-advanced-troubleshooting
+description: |
+  Apply Supabase advanced debugging techniques for hard-to-diagnose issues.
+  Use when standard troubleshooting fails, investigating complex race conditions,
+  or preparing evidence bundles for Supabase support escalation.
+  Trigger with phrases like "supabase hard bug", "supabase mystery error",
+  "supabase impossible to debug", "difficult supabase issue", "supabase deep debug".
+allowed-tools: Read, Grep, Bash(kubectl:*), Bash(curl:*), Bash(tcpdump:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Advanced Troubleshooting
+
+## Overview
+Deep debugging techniques for complex Supabase issues that resist standard troubleshooting.
+
+## Prerequisites
+- Access to production logs and metrics
+- kubectl access to clusters
+- Network capture tools available
+- Understanding of distributed tracing
+
+## Evidence Collection Framework
+
+### Comprehensive Debug Bundle
+```bash
+#!/bin/bash
+# advanced-supabase-debug.sh
+
+BUNDLE="supabase-advanced-debug-$(date +%Y%m%d-%H%M%S)"
+mkdir -p "$BUNDLE"/{logs,metrics,network,config,traces}
+
+# 1. Extended logs (1 hour window)
+kubectl logs -l app=supabase-integration --since=1h > "$BUNDLE/logs/pods.log"
+journalctl -u supabase-service --since "1 hour ago" > "$BUNDLE/logs/system.log"
+
+# 2. Metrics dump
+curl -s localhost:9090/api/v1/query?query=supabase_requests_total > "$BUNDLE/metrics/requests.json"
+curl -s localhost:9090/api/v1/query?query=supabase_errors_total > "$BUNDLE/metrics/errors.json"
+
+# 3. Network capture (30 seconds)
+timeout 30 tcpdump -i any port 443 -w "$BUNDLE/network/capture.pcap" &
+
+# 4. Distributed traces
+curl -s localhost:16686/api/traces?service=supabase > "$BUNDLE/traces/jaeger.json"
+
+# 5. Configuration state
+kubectl get cm supabase-config -o yaml > "$BUNDLE/config/configmap.yaml"
+kubectl get secret supabase-secrets -o yaml > "$BUNDLE/config/secrets-redacted.yaml"
+
+tar -czf "$BUNDLE.tar.gz" "$BUNDLE"
+echo "Advanced debug bundle: $BUNDLE.tar.gz"
+```
+
+## Systematic Isolation
+
+### Layer-by-Layer Testing
+
+```typescript
+// Test each layer independently
+async function diagnoseSupabaseIssue(): Promise<DiagnosisReport> {
+  const results: DiagnosisResult[] = [];
+
+  // Layer 1: Network connectivity
+  results.push(await testNetworkConnectivity());
+
+  // Layer 2: DNS resolution
+  results.push(await testDNSResolution('api.supabase.com'));
+
+  // Layer 3: TLS handshake
+  results.push(await testTLSHandshake('api.supabase.com'));
+
+  // Layer 4: Authentication
+  results.push(await testAuthentication());
+
+  // Layer 5: API response
+  results.push(await testAPIResponse());
+
+  // Layer 6: Response parsing
+  results.push(await testResponseParsing());
+
+  return { results, firstFailure: results.find(r => !r.success) };
+}
+```
+
+### Minimal Reproduction
+
+```typescript
+// Strip down to absolute minimum
+async function minimalRepro(): Promise<void> {
+  // 1. Fresh client, no customization
+  const client = new SupabaseClient({
+    apiKey: process.env.SUPABASE_API_KEY!,
+  });
+
+  // 2. Simplest possible call
+  try {
+    const result = await client.ping();
+    console.log('Ping successful:', result);
+  } catch (error) {
+    console.error('Ping failed:', {
+      message: error.message,
+      code: error.code,
+      stack: error.stack,
+    });
+  }
+}
+```
+
+## Timing Analysis
+
+```typescript
+class TimingAnalyzer {
+  private timings: Map<string, number[]> = new Map();
+
+  async measure<T>(label: string, fn: () => Promise<T>): Promise<T> {
+    const start = performance.now();
+    try {
+      return await fn();
+    } finally {
+      const duration = performance.now() - start;
+      const existing = this.timings.get(label) || [];
+      existing.push(duration);
+      this.timings.set(label, existing);
+    }
+  }
+
+  report(): TimingReport {
+    const report: TimingReport = {};
+    for (const [label, times] of this.timings) {
+      report[label] = {
+        count: times.length,
+        min: Math.min(...times),
+        max: Math.max(...times),
+        avg: times.reduce((a, b) => a + b, 0) / times.length,
+        p95: this.percentile(times, 95),
+      };
+    }
+    return report;
+  }
+}
+```
+
+## Memory and Resource Analysis
+
+```typescript
+// Detect memory leaks in Supabase client usage
+const heapUsed: number[] = [];
+
+setInterval(() => {
+  const usage = process.memoryUsage();
+  heapUsed.push(usage.heapUsed);
+
+  // Alert on sustained growth
+  if (heapUsed.length > 60) { // 1 hour at 1/min
+    const trend = heapUsed[59] - heapUsed[0];
+    if (trend > 100 * 1024 * 1024) { // 100MB growth
+      console.warn('Potential memory leak in supabase integration');
+    }
+  }
+}, 60000);
+```
+
+## Race Condition Detection
+
+```typescript
+// Detect concurrent access issues
+class SupabaseConcurrencyChecker {
+  private inProgress: Set<string> = new Set();
+
+  async execute<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    if (this.inProgress.has(key)) {
+      console.warn(`Concurrent access detected for ${key}`);
+    }
+
+    this.inProgress.add(key);
+    try {
+      return await fn();
+    } finally {
+      this.inProgress.delete(key);
+    }
+  }
+}
+```
+
+## Support Escalation Template
+
+```markdown
+## Supabase Support Escalation
+
+**Severity:** P[1-4]
+**Request ID:** [from error response]
+**Timestamp:** [ISO 8601]
+
+### Issue Summary
+[One paragraph description]
+
+### Steps to Reproduce
+1. [Step 1]
+2. [Step 2]
+
+### Expected vs Actual
+- Expected: [behavior]
+- Actual: [behavior]
+
+### Evidence Attached
+- [ ] Debug bundle (supabase-advanced-debug-*.tar.gz)
+- [ ] Minimal reproduction code
+- [ ] Timing analysis
+- [ ] Network capture (if relevant)
+
+### Workarounds Attempted
+1. [Workaround 1] - Result: [outcome]
+2. [Workaround 2] - Result: [outcome]
+```
+
+## Instructions
+
+### Step 1: Collect Evidence Bundle
+Run the comprehensive debug script to gather all relevant data.
+
+### Step 2: Systematic Isolation
+Test each layer independently to identify the failure point.
+
+### Step 3: Create Minimal Reproduction
+Strip down to the simplest failing case.
+
+### Step 4: Escalate with Evidence
+Use the support template with all collected evidence.
+
+## Output
+- Comprehensive debug bundle collected
+- Failure layer identified
+- Minimal reproduction created
+- Support escalation submitted
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Can't reproduce | Race condition | Add timing analysis |
+| Intermittent failure | Timing-dependent | Increase sample size |
+| No useful logs | Missing instrumentation | Add debug logging |
+| Memory growth | Resource leak | Use heap profiling |
+
+## Examples
+
+### Quick Layer Test
+```bash
+# Test each layer in sequence
+curl -v https://api.supabase.com/health 2>&1 | grep -E "(Connected|TLS|HTTP)"
+```
+
+## Resources
+- [Supabase Support Portal](https://support.supabase.com)
+- [Supabase Status Page](https://status.supabase.com)
+
+## Next Steps
+For load testing, see `supabase-load-scale`.

package/skills/supabase-architecture-variants/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: supabase-architecture-variants
+description: |
+  Choose and implement Supabase validated architecture blueprints for different scales.
+  Use when designing new Supabase integrations, choosing between monolith/service/microservice
+  architectures, or planning migration paths for Supabase applications.
+  Trigger with phrases like "supabase architecture", "supabase blueprint",
+  "how to structure supabase", "supabase project layout", "supabase microservice".
+allowed-tools: Read, Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Architecture Variants
+
+## Overview
+Three validated architecture blueprints for Supabase integrations.
+
+## Prerequisites
+- Understanding of team size and DAU requirements
+- Knowledge of deployment infrastructure
+- Clear SLA requirements
+- Growth projections available
+
+## Variant A: Monolith (Simple)
+
+**Best for:** MVPs, small teams, < 10K daily active users
+
+```
+my-app/
+├── src/
+│   ├── supabase/
+│   │   ├── client.ts          # Singleton client
+│   │   ├── types.ts           # Types
+│   │   └── middleware.ts      # Express middleware
+│   ├── routes/
+│   │   └── api/
+│   │       └── supabase.ts    # API routes
+│   └── index.ts
+├── tests/
+│   └── supabase.test.ts
+└── package.json
+```
+
+### Key Characteristics
+- Single deployment unit
+- Synchronous Supabase calls in request path
+- In-memory caching
+- Simple error handling
+
+### Code Pattern
+```typescript
+// Direct integration in route handler
+app.post('/api/create', async (req, res) => {
+  try {
+    const result = await supabaseClient.create(req.body);
+    res.json(result);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+---
+
+## Variant B: Service Layer (Moderate)
+
+**Best for:** Growing startups, 10K-100K DAU, multiple integrations
+
+```
+my-app/
+├── src/
+│   ├── services/
+│   │   ├── supabase/
+│   │   │   ├── client.ts      # Client wrapper
+│   │   │   ├── service.ts     # Business logic
+│   │   │   ├── repository.ts  # Data access
+│   │   │   └── types.ts
+│   │   └── index.ts           # Service exports
+│   ├── controllers/
+│   │   └── supabase.ts
+│   ├── routes/
+│   ├── middleware/
+│   ├── queue/
+│   │   └── supabase-processor.ts  # Async processing
+│   └── index.ts
+├── config/
+│   └── supabase/
+└── package.json
+```
+
+### Key Characteristics
+- Separation of concerns
+- Background job processing
+- Redis caching
+- Circuit breaker pattern
+- Structured error handling
+
+### Code Pattern
+```typescript
+// Service layer abstraction
+class SupabaseService {
+  constructor(
+    private client: SupabaseClient,
+    private cache: CacheService,
+    private queue: QueueService
+  ) {}
+
+  async createResource(data: CreateInput): Promise<Resource> {
+    // Business logic before API call
+    const validated = this.validate(data);
+
+    // Check cache
+    const cached = await this.cache.get(cacheKey);
+    if (cached) return cached;
+
+    // API call with retry
+    const result = await this.withRetry(() =>
+      this.client.create(validated)
+    );
+
+    // Cache result
+    await this.cache.set(cacheKey, result, 300);
+
+    // Async follow-up
+    await this.queue.enqueue('supabase.post-create', result);
+
+    return result;
+  }
+}
+```
+
+---
+
+## Variant C: Microservice (Complex)
+
+**Best for:** Enterprise, 100K+ DAU, strict SLAs
+
+```
+supabase-service/              # Dedicated microservice
+├── src/
+│   ├── api/
+│   │   ├── grpc/
+│   │   │   └── supabase.proto
+│   │   └── rest/
+│   │       └── routes.ts
+│   ├── domain/
+│   │   ├── entities/
+│   │   ├── events/
+│   │   └── services/
+│   ├── infrastructure/
+│   │   ├── supabase/
+│   │   │   ├── client.ts
+│   │   │   ├── mapper.ts
+│   │   │   └── circuit-breaker.ts
+│   │   ├── cache/
+│   │   ├── queue/
+│   │   └── database/
+│   └── index.ts
+├── config/
+├── k8s/
+│   ├── deployment.yaml
+│   ├── service.yaml
+│   └── hpa.yaml
+└── package.json
+
+other-services/
+├── order-service/       # Calls supabase-service
+├── payment-service/
+└── notification-service/
+```
+
+### Key Characteristics
+- Dedicated Supabase microservice
+- gRPC for internal communication
+- Event-driven architecture
+- Database per service
+- Kubernetes autoscaling
+- Distributed tracing
+- Circuit breaker per service
+
+### Code Pattern
+```typescript
+// Event-driven with domain isolation
+class SupabaseAggregate {
+  private events: DomainEvent[] = [];
+
+  process(command: SupabaseCommand): void {
+    // Domain logic
+    const result = this.execute(command);
+
+    // Emit domain event
+    this.events.push(new SupabaseProcessedEvent(result));
+  }
+
+  getUncommittedEvents(): DomainEvent[] {
+    return [...this.events];
+  }
+}
+
+// Event handler
+@EventHandler(SupabaseProcessedEvent)
+class SupabaseEventHandler {
+  async handle(event: SupabaseProcessedEvent): Promise<void> {
+    // Saga orchestration
+    await this.sagaOrchestrator.continue(event);
+  }
+}
+```
+
+---
+
+## Decision Matrix
+
+| Factor | Monolith | Service Layer | Microservice |
+|--------|----------|---------------|--------------|
+| Team Size | 1-5 | 5-20 | 20+ |
+| DAU | < 10K | 10K-100K | 100K+ |
+| Deployment Frequency | Weekly | Daily | Continuous |
+| Failure Isolation | None | Partial | Full |
+| Operational Complexity | Low | Medium | High |
+| Time to Market | Fastest | Moderate | Slowest |
+
+## Migration Path
+
+```
+Monolith → Service Layer:
+1. Extract Supabase code to service/
+2. Add caching layer
+3. Add background processing
+
+Service Layer → Microservice:
+1. Create dedicated supabase-service repo
+2. Define gRPC contract
+3. Add event bus
+4. Deploy to Kubernetes
+5. Migrate traffic gradually
+```
+
+## Instructions
+
+### Step 1: Assess Requirements
+Use the decision matrix to identify appropriate variant.
+
+### Step 2: Choose Architecture
+Select Monolith, Service Layer, or Microservice based on needs.
+
+### Step 3: Implement Structure
+Set up project layout following the chosen blueprint.
+
+### Step 4: Plan Migration Path
+Document upgrade path for future scaling.
+
+## Output
+- Architecture variant selected
+- Project structure implemented
+- Migration path documented
+- Appropriate patterns applied
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Over-engineering | Wrong variant choice | Start simpler |
+| Performance issues | Wrong layer | Add caching/async |
+| Team friction | Complex architecture | Simplify or train |
+| Deployment complexity | Microservice overhead | Consider service layer |
+
+## Examples
+
+### Quick Variant Check
+```bash
+# Count team size and DAU to select variant
+echo "Team: $(git log --format='%ae' | sort -u | wc -l) developers"
+echo "DAU: Check analytics dashboard"
+```
+
+## Resources
+- [Monolith First](https://martinfowler.com/bliki/MonolithFirst.html)
+- [Microservices Guide](https://martinfowler.com/microservices/)
+- [Supabase Architecture Guide](https://supabase.com/docs/architecture)
+
+## Next Steps
+For common anti-patterns, see `supabase-known-pitfalls`.