@intentsolutionsio/supabase-pack 1.0.0

package/skills/supabase-enterprise-rbac/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: supabase-enterprise-rbac
+description: |
+  Configure Supabase enterprise SSO, role-based access control, and organization management.
+  Use when implementing SSO integration, configuring role-based permissions,
+  or setting up organization-level controls for Supabase.
+  Trigger with phrases like "supabase SSO", "supabase RBAC",
+  "supabase enterprise", "supabase roles", "supabase permissions", "supabase SAML".
+allowed-tools: Read, Write, Edit
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Enterprise RBAC
+
+## Overview
+Configure enterprise-grade access control for Supabase integrations.
+
+## Prerequisites
+- Supabase Enterprise tier subscription
+- Identity Provider (IdP) with SAML/OIDC support
+- Understanding of role-based access patterns
+- Audit logging infrastructure
+
+## Role Definitions
+
+| Role | Permissions | Use Case |
+|------|-------------|----------|
+| Admin | Full access | Platform administrators |
+| Developer | Read/write, no delete | Active development |
+| Viewer | Read-only | Stakeholders, auditors |
+| Service | API access only | Automated systems |
+
+## Role Implementation
+
+```typescript
+enum SupabaseRole {
+  Admin = 'admin',
+  Developer = 'developer',
+  Viewer = 'viewer',
+  Service = 'service',
+}
+
+interface SupabasePermissions {
+  read: boolean;
+  write: boolean;
+  delete: boolean;
+  admin: boolean;
+}
+
+const ROLE_PERMISSIONS: Record<SupabaseRole, SupabasePermissions> = {
+  admin: { read: true, write: true, delete: true, admin: true },
+  developer: { read: true, write: true, delete: false, admin: false },
+  viewer: { read: true, write: false, delete: false, admin: false },
+  service: { read: true, write: true, delete: false, admin: false },
+};
+
+function checkPermission(
+  role: SupabaseRole,
+  action: keyof SupabasePermissions
+): boolean {
+  return ROLE_PERMISSIONS[role][action];
+}
+```
+
+## SSO Integration
+
+### SAML Configuration
+
+```typescript
+// Supabase SAML setup
+const samlConfig = {
+  entryPoint: 'https://idp.company.com/saml/sso',
+  issuer: 'https://supabase.com/saml/metadata',
+  cert: process.env.SAML_CERT,
+  callbackUrl: 'https://app.yourcompany.com/auth/supabase/callback',
+};
+
+// Map IdP groups to Supabase roles
+const groupRoleMapping: Record<string, SupabaseRole> = {
+  'Engineering': SupabaseRole.Developer,
+  'Platform-Admins': SupabaseRole.Admin,
+  'Data-Team': SupabaseRole.Viewer,
+};
+```
+
+### OAuth2/OIDC Integration
+
+```typescript
+import { OAuth2Client } from '@supabase/supabase-js';
+
+const oauthClient = new OAuth2Client({
+  clientId: process.env.SUPABASE_OAUTH_CLIENT_ID!,
+  clientSecret: process.env.SUPABASE_OAUTH_CLIENT_SECRET!,
+  redirectUri: 'https://app.yourcompany.com/auth/supabase/callback',
+  scopes: read, write, realtime,
+});
+```
+
+## Organization Management
+
+```typescript
+interface SupabaseOrganization {
+  id: string;
+  name: string;
+  ssoEnabled: boolean;
+  enforceSso: boolean;
+  allowedDomains: string[];
+  defaultRole: SupabaseRole;
+}
+
+async function createOrganization(
+  config: SupabaseOrganization
+): Promise<void> {
+  await supabaseClient.organizations.create({
+    ...config,
+    settings: {
+      sso: {
+        enabled: config.ssoEnabled,
+        enforced: config.enforceSso,
+        domains: config.allowedDomains,
+      },
+    },
+  });
+}
+```
+
+## Access Control Middleware
+
+```typescript
+function requireSupabasePermission(
+  requiredPermission: keyof SupabasePermissions
+) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const user = req.user as { supabaseRole: SupabaseRole };
+
+    if (!checkPermission(user.supabaseRole, requiredPermission)) {
+      return res.status(403).json({
+        error: 'Forbidden',
+        message: `Missing permission: ${requiredPermission}`,
+      });
+    }
+
+    next();
+  };
+}
+
+// Usage
+app.delete('/supabase/resource/:id',
+  requireSupabasePermission('delete'),
+  deleteResourceHandler
+);
+```
+
+## Audit Trail
+
+```typescript
+interface SupabaseAuditEntry {
+  timestamp: Date;
+  userId: string;
+  role: SupabaseRole;
+  action: string;
+  resource: string;
+  success: boolean;
+  ipAddress: string;
+}
+
+async function logSupabaseAccess(entry: SupabaseAuditEntry): Promise<void> {
+  await auditDb.insert(entry);
+
+  // Alert on suspicious activity
+  if (entry.action === 'delete' && !entry.success) {
+    await alertOnSuspiciousActivity(entry);
+  }
+}
+```
+
+## Instructions
+
+### Step 1: Define Roles
+Map organizational roles to Supabase permissions.
+
+### Step 2: Configure SSO
+Set up SAML or OIDC integration with your IdP.
+
+### Step 3: Implement Middleware
+Add permission checks to API endpoints.
+
+### Step 4: Enable Audit Logging
+Track all access for compliance.
+
+## Output
+- Role definitions implemented
+- SSO integration configured
+- Permission middleware active
+- Audit trail enabled
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| SSO login fails | Wrong callback URL | Verify IdP config |
+| Permission denied | Missing role mapping | Update group mappings |
+| Token expired | Short TTL | Refresh token logic |
+| Audit gaps | Async logging failed | Check log pipeline |
+
+## Examples
+
+### Quick Permission Check
+```typescript
+if (!checkPermission(user.role, 'write')) {
+  throw new ForbiddenError('Write permission required');
+}
+```
+
+## Resources
+- [Supabase Enterprise Guide](https://supabase.com/docs/enterprise)
+- [SAML 2.0 Specification](https://wiki.oasis-open.org/security/FrontPage)
+- [OpenID Connect Spec](https://openid.net/specs/openid-connect-core-1_0.html)
+
+## Next Steps
+For major migrations, see `supabase-migration-deep-dive`.

package/skills/supabase-hello-world/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: supabase-hello-world
+description: |
+  Create a minimal working Supabase example.
+  Use when starting a new Supabase integration, testing your setup,
+  or learning basic Supabase API patterns.
+  Trigger with phrases like "supabase hello world", "supabase example",
+  "supabase quick start", "simple supabase code".
+allowed-tools: Read, Write, Edit
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Hello World
+
+## Overview
+Minimal working example demonstrating core Supabase functionality.
+
+## Prerequisites
+- Completed `supabase-install-auth` setup
+- Valid API credentials configured
+- Development environment ready
+
+## Instructions
+
+### Step 1: Create Entry File
+Create a new file for your hello world example.
+
+### Step 2: Import and Initialize Client
+```typescript
+import { SupabaseClient } from '@supabase/supabase-js';
+
+const client = new SupabaseClient({
+  apiKey: process.env.SUPABASE_API_KEY,
+});
+```
+
+### Step 3: Make Your First API Call
+```typescript
+async function main() {
+  const result = await supabase.from('todos').insert({ task: 'Hello!' }).select(); console.log(result.data);
+}
+
+main().catch(console.error);
+```
+
+## Output
+- Working code file with Supabase client initialization
+- Successful API response confirming connection
+- Console output showing:
+```
+Success! Your Supabase connection is working.
+```
+
+## Error Handling
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Import Error | SDK not installed | Verify with `npm list` or `pip show` |
+| Auth Error | Invalid credentials | Check environment variable is set |
+| Timeout | Network issues | Increase timeout or check connectivity |
+| Rate Limit | Too many requests | Wait and retry with exponential backoff |
+
+## Examples
+
+### TypeScript Example
+```typescript
+import { SupabaseClient } from '@supabase/supabase-js';
+
+const client = new SupabaseClient({
+  apiKey: process.env.SUPABASE_API_KEY,
+});
+
+async function main() {
+  const result = await supabase.from('todos').insert({ task: 'Hello!' }).select(); console.log(result.data);
+}
+
+main().catch(console.error);
+```
+
+### Python Example
+```python
+from supabase import SupabaseClient
+
+client = SupabaseClient()
+
+response = supabase.table('todos').insert({'task': 'Hello!'}).execute(); print(response.data)
+```
+
+## Resources
+- [Supabase Getting Started](https://supabase.com/docs/getting-started)
+- [Supabase API Reference](https://supabase.com/docs/api)
+- [Supabase Examples](https://supabase.com/docs/examples)
+
+## Next Steps
+Proceed to `supabase-local-dev-loop` for development workflow setup.

package/skills/supabase-incident-runbook/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: supabase-incident-runbook
+description: |
+  Execute Supabase incident response procedures with triage, mitigation, and postmortem.
+  Use when responding to Supabase-related outages, investigating errors,
+  or running post-incident reviews for Supabase integration failures.
+  Trigger with phrases like "supabase incident", "supabase outage",
+  "supabase down", "supabase on-call", "supabase emergency", "supabase broken".
+allowed-tools: Read, Grep, Bash(kubectl:*), Bash(curl:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Incident Runbook
+
+## Overview
+Rapid incident response procedures for Supabase-related outages.
+
+## Prerequisites
+- Access to Supabase dashboard and status page
+- kubectl access to production cluster
+- Prometheus/Grafana access
+- Communication channels (Slack, PagerDuty)
+
+## Severity Levels
+
+| Level | Definition | Response Time | Examples |
+|-------|------------|---------------|----------|
+| P1 | Complete outage | < 15 min | Supabase API unreachable |
+| P2 | Degraded service | < 1 hour | High latency, partial failures |
+| P3 | Minor impact | < 4 hours | Webhook delays, non-critical errors |
+| P4 | No user impact | Next business day | Monitoring gaps |
+
+## Quick Triage
+
+```bash
+# 1. Check Supabase status
+curl -s https://status.supabase.com | jq
+
+# 2. Check our integration health
+curl -s https://api.yourapp.com/health | jq '.services.supabase'
+
+# 3. Check error rate (last 5 min)
+curl -s localhost:9090/api/v1/query?query=rate(supabase_errors_total[5m])
+
+# 4. Recent error logs
+kubectl logs -l app=supabase-integration --since=5m | grep -i error | tail -20
+```
+
+## Decision Tree
+
+```
+Supabase API returning errors?
+├─ YES: Is status.supabase.com showing incident?
+│   ├─ YES → Wait for Supabase to resolve. Enable fallback.
+│   └─ NO → Our integration issue. Check credentials, config.
+└─ NO: Is our service healthy?
+    ├─ YES → Likely resolved or intermittent. Monitor.
+    └─ NO → Our infrastructure issue. Check pods, memory, network.
+```
+
+## Immediate Actions by Error Type
+
+### 401/403 - Authentication
+```bash
+# Verify API key is set
+kubectl get secret supabase-secrets -o jsonpath='{.data.api-key}' | base64 -d
+
+# Check if key was rotated
+# → Verify in Supabase dashboard
+
+# Remediation: Update secret and restart pods
+kubectl create secret generic supabase-secrets --from-literal=api-key=NEW_KEY --dry-run=client -o yaml | kubectl apply -f -
+kubectl rollout restart deployment/supabase-integration
+```
+
+### 429 - Rate Limited
+```bash
+# Check rate limit headers
+curl -v https://api.supabase.com 2>&1 | grep -i rate
+
+# Enable request queuing
+kubectl set env deployment/supabase-integration RATE_LIMIT_MODE=queue
+
+# Long-term: Contact Supabase for limit increase
+```
+
+### 500/503 - Supabase Errors
+```bash
+# Enable graceful degradation
+kubectl set env deployment/supabase-integration SUPABASE_FALLBACK=true
+
+# Notify users of degraded service
+# Update status page
+
+# Monitor Supabase status for resolution
+```
+
+## Communication Templates
+
+### Internal (Slack)
+```
+🔴 P1 INCIDENT: Supabase Integration
+Status: INVESTIGATING
+Impact: [Describe user impact]
+Current action: [What you're doing]
+Next update: [Time]
+Incident commander: @[name]
+```
+
+### External (Status Page)
+```
+Supabase Integration Issue
+
+We're experiencing issues with our Supabase integration.
+Some users may experience [specific impact].
+
+We're actively investigating and will provide updates.
+
+Last updated: [timestamp]
+```
+
+## Post-Incident
+
+### Evidence Collection
+```bash
+# Generate debug bundle
+./scripts/supabase-debug-bundle.sh
+
+# Export relevant logs
+kubectl logs -l app=supabase-integration --since=1h > incident-logs.txt
+
+# Capture metrics
+curl "localhost:9090/api/v1/query_range?query=supabase_errors_total&start=2h" > metrics.json
+```
+
+### Postmortem Template
+```markdown
+## Incident: Supabase [Error Type]
+**Date:** YYYY-MM-DD
+**Duration:** X hours Y minutes
+**Severity:** P[1-4]
+
+### Summary
+[1-2 sentence description]
+
+### Timeline
+- HH:MM - [Event]
+- HH:MM - [Event]
+
+### Root Cause
+[Technical explanation]
+
+### Impact
+- Users affected: N
+- Revenue impact: $X
+
+### Action Items
+- [ ] [Preventive measure] - Owner - Due date
+```
+
+## Instructions
+
+### Step 1: Quick Triage
+Run the triage commands to identify the issue source.
+
+### Step 2: Follow Decision Tree
+Determine if the issue is Supabase-side or internal.
+
+### Step 3: Execute Immediate Actions
+Apply the appropriate remediation for the error type.
+
+### Step 4: Communicate Status
+Update internal and external stakeholders.
+
+## Output
+- Issue identified and categorized
+- Remediation applied
+- Stakeholders notified
+- Evidence collected for postmortem
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Can't reach status page | Network issue | Use mobile or VPN |
+| kubectl fails | Auth expired | Re-authenticate |
+| Metrics unavailable | Prometheus down | Check backup metrics |
+| Secret rotation fails | Permission denied | Escalate to admin |
+
+## Examples
+
+### One-Line Health Check
+```bash
+curl -sf https://api.yourapp.com/health | jq '.services.supabase.status' || echo "UNHEALTHY"
+```
+
+## Resources
+- [Supabase Status Page](https://status.supabase.com)
+- [Supabase Support](https://support.supabase.com)
+
+## Next Steps
+For data handling, see `supabase-data-handling`.

package/skills/supabase-install-auth/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: supabase-install-auth
+description: |
+  Install and configure Supabase SDK/CLI authentication.
+  Use when setting up a new Supabase integration, configuring API keys,
+  or initializing Supabase in your project.
+  Trigger with phrases like "install supabase", "setup supabase",
+  "supabase auth", "configure supabase API key".
+allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Supabase Install & Auth
+
+## Overview
+Set up Supabase SDK/CLI and configure authentication credentials.
+
+## Prerequisites
+- Node.js 18+ or Python 3.10+
+- Package manager (npm, pnpm, or pip)
+- Supabase account with API access
+- API key from Supabase dashboard
+
+## Instructions
+
+### Step 1: Install SDK
+```bash
+# Node.js
+npm install @supabase/supabase-js
+
+# Python
+pip install supabase
+```
+
+### Step 2: Configure Authentication
+```bash
+# Set environment variable
+export SUPABASE_API_KEY="your-api-key"
+
+# Or create .env file
+echo 'SUPABASE_API_KEY=your-api-key' >> .env
+```
+
+### Step 3: Verify Connection
+```typescript
+const result = await supabase.from('_test').select('*').limit(1); console.log(result.error ? 'Failed' : 'OK');
+```
+
+## Output
+- Installed SDK package in node_modules or site-packages
+- Environment variable or .env file with API key
+- Successful connection verification output
+
+## Error Handling
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Invalid API Key | Incorrect or expired key | Verify key in Supabase dashboard |
+| Rate Limited | Exceeded quota | Check quota at https://supabase.com/docs |
+| Network Error | Firewall blocking | Ensure outbound HTTPS allowed |
+| Module Not Found | Installation failed | Run `npm install` or `pip install` again |
+
+## Examples
+
+### TypeScript Setup
+```typescript
+import { SupabaseClient } from '@supabase/supabase-js';
+
+const client = new SupabaseClient({
+  apiKey: process.env.SUPABASE_API_KEY,
+});
+```
+
+### Python Setup
+```python
+from supabase import SupabaseClient
+
+client = SupabaseClient(
+    api_key=os.environ.get('SUPABASE_API_KEY')
+)
+```
+
+## Resources
+- [Supabase Documentation](https://supabase.com/docs)
+- [Supabase Dashboard](https://api.supabase.com)
+- [Supabase Status](https://status.supabase.com)
+
+## Next Steps
+After successful auth, proceed to `supabase-hello-world` for your first API call.