@polymorphism-tech/morph-spec 4.3.3 → 4.3.4

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

@@ -1,252 +0,0 @@
-# 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/stacks/nextjs-supabase/.morph/standards/infrastructure/supabase/supabase-auth.md

@@ -1,176 +0,0 @@
-# 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/stacks/nextjs-supabase/.morph/standards/infrastructure/supabase/supabase-pgvector.md

@@ -1,169 +0,0 @@
-# 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 |