@polymorphism-tech/morph-spec 4.8.19 → 4.10.0

package/framework/standards/infrastructure/vercel/vercel-database.md

@@ -0,0 +1,106 @@
+# Vercel Deployment — Database Standard
+
+> **Scope:** nextjs-vercel
+> **Layer:** 1 (always-on for Vercel-deployed Next.js)
+> **Keywords:** vercel, neon, planetscale, serverless database, serverless postgres, deploy nextjs
+> **Load When:** deployment target is Vercel with Next.js stack
+
+---
+
+## Rule: Vercel Requires a Serverless Database
+
+**NEVER** use a traditional long-lived database connection pool (PostgreSQL TCP, MySQL TCP) with Vercel.
+Vercel functions are ephemeral and stateless — each invocation may spawn a fresh process.
+A persistent connection pool (e.g., EF Core + plain Npgsql TCP) will exhaust database connection limits within minutes under moderate load.
+
+**ALWAYS** use a **serverless-compatible** database when deploying to Vercel.
+
+---
+
+## Approved Serverless Databases
+
+| Provider | Type | Connection mode | Notes |
+|----------|------|-----------------|-------|
+| **Neon** | PostgreSQL (serverless) | HTTP (`@neondatabase/serverless`) or pooled TCP via PgBouncer | First choice for SQL |
+| **PlanetScale** | MySQL-compatible (serverless) | HTTP driver (`@planetscale/database`) | Good for MySQL ecosystems |
+| **Supabase** | PostgreSQL + PgBouncer | Pooled TCP (transaction mode) or REST | Full BaaS option |
+| **Turso** | SQLite (distributed) | HTTP (`@libsql/client`) | Lightweight, edge-friendly |
+
+---
+
+## Implementation: Neon (Recommended)
+
+```ts
+// lib/db.ts
+import { neon } from '@neondatabase/serverless';
+
+const sql = neon(process.env.DATABASE_URL!);
+export default sql;
+```
+
+```ts
+// Example: API Route (app/api/items/route.ts)
+import sql from '@/lib/db';
+
+export async function GET() {
+  const items = await sql`SELECT * FROM items LIMIT 50`;
+  return Response.json(items);
+}
+```
+
+### Environment variable
+```
+DATABASE_URL=postgresql://user:pass@ep-xxx.neon.tech/dbname?sslmode=require
+```
+
+---
+
+## Implementation: Supabase + PgBouncer (Transaction Mode)
+
+Use the **port 6543** connection string (PgBouncer, transaction pooling):
+
+```
+DATABASE_URL=postgresql://user:pass@db.xxx.supabase.co:6543/postgres?pgbouncer=true&connection_limit=1
+```
+
+If using an ORM (Prisma/Drizzle), set `connection_limit=1` to avoid pool saturation.
+
+---
+
+## Anti-patterns — NEVER use with Vercel
+
+```ts
+// WRONG: plain Npgsql/pg pool without serverless adapter
+import { Pool } from 'pg';
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+// → Leaks connections on every cold start
+
+// WRONG: EF Core (dotnet) TCP pool behind a Vercel-deployed Next.js API route
+// → Not applicable (EF Core is .NET), but calling a .NET API that pools
+//   connections is fine as long as the .NET side runs on a persistent server
+```
+
+---
+
+## Decision Tree: Choose Your DB Tier
+
+```
+Deploying to Vercel?
+  └── YES → Use serverless DB
+        ├── Need SQL + PostGIS/pgvector? → Neon
+        ├── Need full BaaS (auth, storage, RLS)? → Supabase
+        ├── MySQL ecosystem? → PlanetScale
+        └── Edge-only, lightweight? → Turso
+  └── NO (EasyPanel, Railway, Render, Azure Container Apps)
+        └── Any PostgreSQL with connection pool is fine
+```
+
+---
+
+## Validator Check (design phase)
+
+During `phase-design`, the standards agent must verify:
+
+- `config.deployment.target === 'vercel'` → enforce serverless DB selection
+- If `database.provider` is missing or is `postgresql-tcp`, flag as **BLOCKING** issue
+- Add to `decisions.md`: "Database must be serverless-compatible (Vercel constraint)"

package/framework/standards/integration/mcp/mcp-tools.md

@@ -49,15 +49,10 @@ const repo = await mcp__github__get_repo();
 
 | MCP | Use Case | Example |
 |-----|----------|---------|
-| **Figma** | Extract design tokens, components | `mcp__figma__get_file({ fileKey })` |
 | **Playwright** | Navigate, screenshot, inspect live pages | `mcp__playwright__browser_navigate({ url })` |
 | **Context7** | Component library documentation | `mcp__context7__query_docs({ libraryId, query })` |
 
 ```javascript
-// Get design tokens from Figma
-const file = await mcp__figma__get_file({ fileKey: "abc123" });
-// → colors, typography, spacing from design file
-
 // Screenshot existing app for design reference
 await mcp__playwright__browser_navigate({ url: "https://app.example.com/dashboard" });
 const screenshot = await mcp__playwright__browser_take_screenshot();
@@ -180,6 +175,7 @@ for (const task of tasks) {
 | **GitHub** | Create PR, push branches | `mcp__github__create_pull_request()` |
 | **Context7** | Look up API usage during coding | `mcp__context7__query_docs()` |
 | **Playwright** | Smoke test deployed features, verify UI | `mcp__playwright__browser_navigate()` |
+| **Vercel** | Deploy, check logs, manage env vars | `mcp__vercel__list_projects()` |
 | **Azure** | Provision resources, check deployment status | Provider-specific |
 | **Docker** | Build images, manage containers | Provider-specific |
 
@@ -214,7 +210,25 @@ const logs = await mcp__playwright__browser_console_messages();
 // Screenshot for recap.md documentation
 const screenshot = await mcp__playwright__browser_take_screenshot();
 
-// Fallback: Bash for migrations, gh CLI for PRs
+// === VERCEL (Deployment & Environment) ===
+
+// List projects
+const projects = await mcp__vercel__list_projects();
+
+// Check deployment status and logs
+const deployments = await mcp__vercel__get_deployments({ projectId: 'my-project' });
+const logs = await mcp__vercel__get_deployment_logs({ deploymentId: deployments[0].uid });
+
+// Manage environment variables
+await mcp__vercel__manage_env_vars({
+  projectId: 'my-project',
+  action: 'set',
+  key: 'DATABASE_URL',
+  value: process.env.DATABASE_URL,
+  target: ['production', 'preview']
+});
+
+// Fallback: Bash for migrations, gh CLI for PRs, vercel CLI for deployments
 ```
 
 ---
@@ -225,7 +239,6 @@ const screenshot = await mcp__playwright__browser_take_screenshot();
 |------|----------|--------------------|
 | Database schema | Supabase/DB MCP | Grep queries + Read types |
 | Repo metadata | GitHub MCP | Bash `gh` CLI |
-| Design tokens | Figma MCP | Read CSS/SCSS variables |
 | Library docs | Context7 | WebSearch + WebFetch |
 | Live page preview | Playwright MCP | WebFetch URL |
 | Page interaction (click, type, navigate) | Playwright MCP | Manual testing |
@@ -233,6 +246,7 @@ const screenshot = await mcp__playwright__browser_take_screenshot();
 | Console error checking | Playwright MCP (`browser_console_messages`) | Browser DevTools |
 | Container ops | Docker MCP | Bash `docker` CLI |
 | Cloud resources | Azure MCP | Bash `az` CLI |
+| Vercel deployments | Vercel MCP | Bash `vercel` CLI |
 
 **Rule:** MCP tools provide structured data (JSON responses). Native tools require manual parsing. **Always prefer MCP when available** — fall back to native when not.
 
@@ -332,6 +346,8 @@ await mcp__playwright__browser_file_upload({ ref: "s1e20", paths: ["/path/to/fil
 
 ### Supabase: Full Schema Discovery
 
+> **v4 config:** Remote OAuth — `{ "type": "http", "url": "https://mcp.supabase.com/mcp" }`. Authenticate via `/mcp` in Claude Code.
+
 ```javascript
 // Complete workflow for Phase 2 schema analysis
 const tables = await mcp__supabase__list_tables();
@@ -362,6 +378,8 @@ const docs = await mcp__context7__query_docs({
 
 ### GitHub: Code Search Across Repo
 
+> **v4 config:** Docker — `{ "command": "docker", "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"] }`. Requires Docker Desktop.
+
 ```javascript
 // Find patterns in large codebase during Phase 2
 const results = await mcp__github__search_code({