@polymorphism-tech/morph-spec 4.3.4 → 4.3.6

package/.morph/standards/infrastructure/supabase/mcp-setup.md

@@ -0,0 +1,252 @@
+# Supabase MCP Server Setup Guide
+
+> **Scope:** nextjs-supabase
+> **Layer:** 2 (on keyword)
+> **Keywords:** supabase, mcp, setup, model context protocol
+> **Load When:** supabase mcp setup keywords detected
+
+Direct database management from Claude Code via Model Context Protocol
+
+## What It Provides
+
+The Supabase MCP Server lets Claude Code interact directly with your Supabase project's database. This enables:
+
+- Running SQL queries and viewing results
+- Creating and managing database migrations
+- Inspecting table schemas, indexes, and RLS policies
+- Managing Supabase Auth, Storage, and Edge Functions
+- Schema diffing and migration generation
+
+## CRITICAL WARNING
+
+```
+==========================================================
+  NEVER connect to a PRODUCTION Supabase project via MCP.
+
+  MCP provides direct database access. A single bad query
+  can DROP tables, DELETE data, or DISABLE RLS.
+
+  ONLY connect to:
+  - Local Supabase (supabase start)
+  - Development/staging projects
+  - Disposable test projects
+==========================================================
+```
+
+## Setup
+
+### 1. Get Your Supabase Connection Details
+
+From your Supabase Dashboard > Project Settings > API:
+- **Project URL**: `https://xxxxxxxxxxxx.supabase.co`
+- **Service Role Key**: `eyJhbGc...` (Settings > API > service_role key)
+
+For local Supabase (`supabase start`):
+- **Project URL**: `http://127.0.0.1:54321`
+- **Service Role Key**: Output from `supabase status`
+
+### 2. Configure Claude Desktop / Claude Code
+
+Add the Supabase MCP server to your configuration.
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@supabase/mcp-server-supabase@latest",
+        "--supabase-url",
+        "https://xxxxxxxxxxxx.supabase.co",
+        "--supabase-service-role-key",
+        "eyJhbGc...",
+        "--read-only"
+      ]
+    }
+  }
+}
+```
+
+**Claude Code** (`.claude/settings.local.json`):
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@supabase/mcp-server-supabase@latest",
+        "--supabase-url",
+        "https://xxxxxxxxxxxx.supabase.co",
+        "--supabase-service-role-key",
+        "eyJhbGc...",
+        "--read-only"
+      ]
+    }
+  }
+}
+```
+
+### 3. Default: Read-Only Mode
+
+The `--read-only` flag is included by default. In this mode:
+
+| Operation | Allowed |
+|-----------|---------|
+| SELECT queries | Yes |
+| DESCRIBE / schema inspection | Yes |
+| LIST tables, policies, indexes | Yes |
+| INSERT / UPDATE / DELETE | No |
+| CREATE / ALTER / DROP | No |
+| Migration creation | No |
+
+To enable write access (development only), remove `--read-only`:
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@supabase/mcp-server-supabase@latest",
+        "--supabase-url",
+        "http://127.0.0.1:54321",
+        "--supabase-service-role-key",
+        "your-local-service-role-key"
+      ]
+    }
+  }
+}
+```
+
+Write mode should ONLY be used with local Supabase or disposable dev projects.
+
+## Available Tool Groups
+
+The Supabase MCP Server exposes these tool groups:
+
+### Database Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_tables` | List all tables in the project |
+| `list_extensions` | List installed PostgreSQL extensions |
+| `list_migrations` | List applied migrations |
+| `apply_migration` | Apply a new SQL migration |
+| `execute_sql` | Run arbitrary SQL (read-only by default) |
+| `get_migration_status` | Check pending vs applied migrations |
+
+### Auth Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_auth_config` | View auth provider configuration |
+| `list_auth_users` | List authenticated users |
+
+### Storage Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_storage_buckets` | List storage buckets |
+| `get_storage_config` | View storage configuration |
+
+### Project Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_project_config` | View project settings |
+| `get_project_api_keys` | View API keys |
+
+## Usage for Migrations and Schema Management
+
+### Inspecting Current Schema
+
+Ask Claude Code to use the MCP tools:
+
+```
+"Show me all tables and their RLS policies"
+"What indexes exist on the documents table?"
+"List all migrations applied so far"
+```
+
+### Creating Migrations
+
+With write mode enabled on a local/dev project:
+
+```
+"Create a migration to add a 'tags' column to the documents table"
+"Add an RLS policy so only tenant admins can delete documents"
+"Enable the pgvector extension and create the embedding column"
+```
+
+The MCP server will generate and apply SQL migrations through Supabase's migration system.
+
+### Schema Diffing
+
+```
+"Compare the current schema against the migration files"
+"Show me what would change if I apply the pending migration"
+```
+
+## Usage with MORPH-SPEC Workflow
+
+During MORPH-SPEC phases, the MCP server is useful for:
+
+| Phase | MCP Usage |
+|-------|-----------|
+| **Phase 2 (Design)** | Inspect existing schema to inform spec |
+| **Phase 4 (Tasks)** | Verify migration dependencies |
+| **Phase 5 (Implement)** | Apply migrations, verify RLS policies, test queries |
+
+### Example Workflow
+
+```
+1. Design phase: "List current tables and extensions"
+2. Write migration SQL in supabase/migrations/
+3. Apply via MCP: "Apply migration 003_add_search_logs.sql"
+4. Verify: "Show RLS policies on search_logs table"
+5. Test: "Run SELECT * FROM search_logs LIMIT 5"
+```
+
+## Security Best Practices
+
+1. **Always use `--read-only` unless actively running migrations**
+2. **Never store service_role keys in version control** -- use environment variables or a secrets manager
+3. **Use local Supabase for development** (`supabase start`) instead of cloud projects
+4. **Rotate keys if accidentally exposed** -- Supabase Dashboard > Settings > API > Regenerate
+5. **Restrict MCP to development machines only** -- never configure on CI/CD or shared servers
+6. **Review SQL before applying** -- the MCP server executes SQL with service_role privileges, bypassing all RLS
+
+### Environment Variable Alternative
+
+Instead of hardcoding keys in the config file:
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@supabase/mcp-server-supabase@latest",
+        "--read-only"
+      ],
+      "env": {
+        "SUPABASE_URL": "${SUPABASE_URL}",
+        "SUPABASE_SERVICE_ROLE_KEY": "${SUPABASE_SERVICE_ROLE_KEY}"
+      }
+    }
+  }
+}
+```
+
+Set the environment variables in your shell profile or `.env` file (never committed).
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/standards/infrastructure/supabase/supabase-auth.md

@@ -0,0 +1,176 @@
+# Supabase Authentication Standard
+
+> **Scope:** nextjs-supabase
+> **Layer:** 2 (on keyword)
+> **Keywords:** supabase, auth, rls, user, authentication
+> **Load When:** supabase auth keywords detected
+
+Stack: Next.js 15 + Supabase + .NET Backend
+
+## Core Rules
+
+- NEVER use `supabase.auth.getSession()` on server -- reads from cookies without validation
+- ALWAYS use `supabase.auth.getUser()` on server -- validates JWT with Supabase
+- NEVER expose `service_role` key on frontend -- bypasses RLS
+- ALWAYS use `@supabase/ssr` for Next.js -- not `@supabase/auth-helpers-nextjs` (deprecated)
+- ALWAYS use PKCE flow for SSR auth
+
+## Client Setup
+
+### Browser Client
+
+```ts
+// lib/supabase/client.ts
+import { createBrowserClient } from "@supabase/ssr";
+
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+  );
+}
+```
+
+### Server Client
+
+```ts
+// lib/supabase/server.ts
+import { createServerClient } from "@supabase/ssr";
+import { cookies } from "next/headers";
+
+export async function createClient() {
+  const cookieStore = await cookies();
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() { return cookieStore.getAll(); },
+        setAll(cookiesToSet) {
+          cookiesToSet.forEach(({ name, value, options }) =>
+            cookieStore.set(name, value, options));
+        },
+      },
+    }
+  );
+}
+```
+
+## Auth Flows
+
+```ts
+// Email/Password sign up
+await supabase.auth.signUp({ email, password,
+  options: { emailRedirectTo: `${origin}/auth/callback` } });
+
+// Email/Password sign in
+await supabase.auth.signInWithPassword({ email, password });
+
+// OAuth (Google / GitHub)
+await supabase.auth.signInWithOAuth({
+  provider: "google", // or "github"
+  options: { redirectTo: `${origin}/auth/callback`,
+    queryParams: { access_type: "offline", prompt: "consent" } } // Google-specific
+});
+
+// Magic Link
+await supabase.auth.signInWithOtp({ email,
+  options: { emailRedirectTo: `${origin}/auth/callback` } });
+```
+
+## Auth Callback Route (PKCE)
+
+```ts
+// app/auth/callback/route.ts
+import { createClient } from "@/lib/supabase/server";
+import { NextResponse } from "next/server";
+
+export async function GET(request: Request) {
+  const { searchParams, origin } = new URL(request.url);
+  const code = searchParams.get("code");
+  const next = searchParams.get("next") ?? "/dashboard";
+  if (code) {
+    const supabase = await createClient();
+    const { error } = await supabase.auth.exchangeCodeForSession(code);
+    if (!error) return NextResponse.redirect(`${origin}${next}`);
+  }
+  return NextResponse.redirect(`${origin}/auth/error`);
+}
+```
+
+## Middleware Pattern
+
+```ts
+// middleware.ts
+import { createServerClient } from "@supabase/ssr";
+import { NextResponse, type NextRequest } from "next/server";
+
+export async function middleware(request: NextRequest) {
+  let supabaseResponse = NextResponse.next({ request });
+  const supabase = createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() { return request.cookies.getAll(); },
+        setAll(cookiesToSet) {
+          cookiesToSet.forEach(({ name, value, options }) => {
+            request.cookies.set(name, value);
+            supabaseResponse.cookies.set(name, value, options);
+          });
+        },
+      },
+    }
+  );
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user && request.nextUrl.pathname.startsWith("/dashboard"))
+    return NextResponse.redirect(new URL("/login", request.url));
+  return supabaseResponse;
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico|api/webhooks).*)"],
+};
+```
+
+## .NET JWT Validation
+
+```csharp
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddJwtBearer(options => {
+        options.TokenValidationParameters = new TokenValidationParameters {
+            ValidateIssuer = true,
+            ValidIssuer = $"https://{supabaseProjectRef}.supabase.co/auth/v1",
+            ValidateAudience = true,
+            ValidAudience = "authenticated",
+            ValidateIssuerSigningKey = true,
+            IssuerSigningKey = new SymmetricSecurityKey(
+                Encoding.UTF8.GetBytes(supabaseJwtSecret)),
+            ValidateLifetime = true,
+            ClockSkew = TimeSpan.FromSeconds(30)
+        };
+    });
+
+// Extract user ID: maps to auth.uid()
+var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
+```
+
+## Environment Variables
+
+| Variable | Where | Purpose |
+|----------|-------|---------|
+| `NEXT_PUBLIC_SUPABASE_URL` | Frontend | Supabase project URL |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Frontend | Public anon key (respects RLS) |
+| `SUPABASE_SERVICE_ROLE_KEY` | Backend ONLY | Bypasses RLS -- NEVER on frontend |
+| `SUPABASE_JWT_SECRET` | Backend ONLY | JWT validation secret |
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `getSession()` on server | `getUser()` on server | getSession reads unvalidated cookie data |
+| `@supabase/auth-helpers-nextjs` | `@supabase/ssr` | auth-helpers is deprecated |
+| `service_role` in `NEXT_PUBLIC_*` | `anon` key in `NEXT_PUBLIC_*` | service_role bypasses all RLS |
+| Implicit flow for SSR | PKCE flow with code exchange | Implicit exposes tokens in URL fragments |
+| Auth only in page components | Auth check in middleware.ts | Middleware prevents flash of content |
+| Missing `setAll` in cookie config | Both `getAll` and `setAll` | Session refresh silently fails without setAll |

package/.morph/standards/infrastructure/supabase/supabase-pgvector.md

@@ -0,0 +1,169 @@
+# Supabase pgvector Standard
+
+> **Scope:** nextjs-supabase
+> **Layer:** 2 (on keyword)
+> **Keywords:** supabase, pgvector, embedding, similarity, vector search
+> **Load When:** supabase pgvector keywords detected
+
+Stack: Next.js 15 + Supabase + .NET Backend
+
+## Core Rules
+
+- ALWAYS use HNSW indexes for production (faster queries, no training required)
+- ALWAYS match dimensions to embedding model (e.g., 1536 for text-embedding-3-small)
+- NEVER store embeddings without an index -- full table scan at query time
+- Use `halfvec` for large datasets to halve storage (16-bit vs 32-bit per dimension)
+- ALWAYS use RLS on tables containing embeddings
+
+## Setup and Table Design
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE documents (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES auth.users(id),
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  metadata JSONB DEFAULT '{}',
+  embedding vector(1536),
+  created_at TIMESTAMPTZ DEFAULT now()
+);
+
+ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
+CREATE POLICY "owner_access" ON documents FOR ALL
+  USING (user_id = auth.uid()) WITH CHECK (user_id = auth.uid());
+CREATE INDEX idx_documents_user_id ON documents (user_id);
+```
+
+### halfvec Optimization
+
+| Type | Storage/dim | 1536-dim | Best for |
+|------|------------|----------|----------|
+| `vector` | 4 bytes | 6 KB | High precision, small datasets |
+| `halfvec` | 2 bytes | 3 KB | Large datasets, cost optimization |
+
+## Index Types
+
+```sql
+-- HNSW (recommended)
+CREATE INDEX idx_docs_embedding ON documents
+  USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);
+
+-- IVFFlat (legacy, requires existing data)
+CREATE INDEX idx_docs_ivf ON documents
+  USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+```
+
+| Feature | HNSW | IVFFlat |
+|---------|------|---------|
+| Query speed | Faster | Slower |
+| Requires training | No | Yes |
+| Recall quality | Higher | Lower |
+| Recommended | Yes | Only for very large datasets |
+
+## HNSW Parameters
+
+| Parameter | Default | Tuning |
+|-----------|---------|--------|
+| `m` | 16 | Higher = better recall, more memory |
+| `ef_construction` | 64 | Higher = better index, slower build |
+| `ef_search` | 40 | `SET hnsw.ef_search = 100;` per session |
+
+## Distance Functions
+
+| Operator | Function | Index Ops | Use Case |
+|----------|----------|-----------|----------|
+| `<=>` | Cosine distance | `vector_cosine_ops` | Normalized embeddings (most common) |
+| `<->` | L2 (Euclidean) | `vector_l2_ops` | Spatial/positional data |
+| `<#>` | Inner product (neg) | `vector_ip_ops` | Pre-normalized, max similarity |
+
+## Similarity Search
+
+```sql
+CREATE OR REPLACE FUNCTION match_documents(
+  query_embedding vector(1536),
+  match_threshold float DEFAULT 0.78,
+  match_count int DEFAULT 10,
+  p_user_id uuid DEFAULT auth.uid()
+) RETURNS TABLE (id uuid, title text, content text, similarity float)
+LANGUAGE sql STABLE AS $$
+  SELECT d.id, d.title, d.content,
+    1 - (d.embedding <=> query_embedding) AS similarity
+  FROM documents d
+  WHERE d.user_id = p_user_id
+    AND 1 - (d.embedding <=> query_embedding) > match_threshold
+  ORDER BY d.embedding <=> query_embedding
+  LIMIT match_count;
+$$;
+```
+
+## Hybrid Search (Vector + Full-Text)
+
+```sql
+CREATE OR REPLACE FUNCTION hybrid_search(
+  query_text text, query_embedding vector(1536),
+  match_count int DEFAULT 10,
+  text_weight float DEFAULT 0.3, vector_weight float DEFAULT 0.7
+) RETURNS TABLE (id uuid, title text, content text, score float)
+LANGUAGE sql STABLE AS $$
+  WITH vector_results AS (
+    SELECT id, title, content,
+      1 - (embedding <=> query_embedding) AS vector_score
+    FROM documents WHERE user_id = auth.uid()
+    ORDER BY embedding <=> query_embedding LIMIT match_count * 2
+  ),
+  text_results AS (
+    SELECT id, title, content,
+      ts_rank(to_tsvector('english', content), plainto_tsquery('english', query_text)) AS text_score
+    FROM documents WHERE user_id = auth.uid()
+      AND to_tsvector('english', content) @@ plainto_tsquery('english', query_text)
+    LIMIT match_count * 2
+  )
+  SELECT COALESCE(v.id, t.id), COALESCE(v.title, t.title), COALESCE(v.content, t.content),
+    (COALESCE(v.vector_score, 0) * vector_weight + COALESCE(t.text_score, 0) * text_weight)
+  FROM vector_results v FULL OUTER JOIN text_results t ON v.id = t.id
+  ORDER BY score DESC LIMIT match_count;
+$$;
+```
+
+## .NET Integration (Npgsql)
+
+```csharp
+public sealed class DocumentRepository(AppDbContext db)
+{
+    public async Task StoreEmbeddingAsync(
+        Guid documentId, float[] embedding, CancellationToken ct = default)
+    {
+        await db.Database.ExecuteSqlInterpolatedAsync(
+            $"UPDATE documents SET embedding = {new Vector(embedding)} WHERE id = {documentId}", ct);
+    }
+
+    public async Task<List<DocumentMatch>> SearchSimilarAsync(
+        float[] queryEmbedding, int limit = 10, float threshold = 0.78f,
+        CancellationToken ct = default)
+    {
+        return await db.Database.SqlQuery<DocumentMatch>($"""
+            SELECT id, title, content,
+              1 - (embedding <=> {new Vector(queryEmbedding)}::vector) AS similarity
+            FROM documents
+            WHERE 1 - (embedding <=> {new Vector(queryEmbedding)}::vector) > {threshold}
+            ORDER BY embedding <=> {new Vector(queryEmbedding)}::vector LIMIT {limit}
+            """).ToListAsync(ct);
+    }
+}
+
+// EF Core registration
+builder.Services.AddDbContext<AppDbContext>(o =>
+    o.UseNpgsql(connectionString, npg => npg.UseVector()));
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| No index on embedding column | HNSW index | Full table scan, extremely slow |
+| `ORDER BY similarity DESC` | `ORDER BY embedding <=> query ASC` | Operator returns distance, not similarity |
+| Mixing embedding dimensions | Consistent dimensions per column | Dimension mismatch causes runtime errors |
+| Full-precision for millions of rows | `halfvec` for large datasets | 2x storage savings, minimal quality loss |
+| Missing RLS on embedding tables | RLS with user/tenant policies | Embeddings contain sensitive content context |