@polymorphism-tech/morph-spec 3.2.0 → 4.3.0

package/stacks/nextjs-supabase/.morph/docs/easypanel-setup.md

@@ -1,169 +0,0 @@
-# EasyPanel Setup Guide
-
-> Deploy .NET API + Next.js to VPS via EasyPanel
-
-## Prerequisites
-
-- VPS with EasyPanel installed (Ubuntu 22.04+ recommended)
-- GitHub repository with Dockerfiles
-- Domain name (optional, EasyPanel provides subdomains)
-
-## 1. GitHub Integration
-
-### Create Personal Access Token (PAT)
-
-1. GitHub > Settings > Developer Settings > Personal Access Tokens > Fine-grained
-2. Repository access: select your repo
-3. Permissions: Contents (read), Metadata (read)
-4. Copy token for EasyPanel
-
-### Connect in EasyPanel
-
-1. EasyPanel Dashboard > Settings > Git
-2. Add GitHub provider with PAT
-3. Test connection
-
-## 2. Create Project
-
-```
-EasyPanel Dashboard > Projects > Create Project
-Name: my-saas-app
-```
-
-## 3. Configure Services
-
-### API Service (.NET)
-
-| Setting | Value |
-|---------|-------|
-| Type | App |
-| Source | GitHub |
-| Repository | your-org/your-repo |
-| Branch | main |
-| Build Path | . |
-| Dockerfile | Dockerfile.api |
-| Port | 8080 |
-
-### Web Service (Next.js)
-
-| Setting | Value |
-|---------|-------|
-| Type | App |
-| Source | GitHub |
-| Repository | your-org/your-repo |
-| Branch | main |
-| Build Path | . |
-| Dockerfile | Dockerfile.web |
-| Port | 3000 |
-
-## 4. Environment Variables
-
-### API (.NET)
-
-```
-ASPNETCORE_ENVIRONMENT=Production
-SUPABASE_URL=https://xxx.supabase.co
-SUPABASE_SERVICE_ROLE_KEY=eyJ...
-SUPABASE_JWT_SECRET=your-jwt-secret
-ASPNETCORE_URLS=http://+:8080
-```
-
-### Web (Next.js)
-
-```
-NODE_ENV=production
-NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
-NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
-NEXT_PUBLIC_API_URL=https://api.yourdomain.com
-```
-
-CRITICAL: Never commit secrets. Use EasyPanel env vars panel only.
-
-## 5. Domain + SSL
-
-### Custom Domain
-
-1. Service > Domains > Add Domain
-2. Enter: `api.yourdomain.com` (for API) or `app.yourdomain.com` (for web)
-3. DNS: Add A record pointing to VPS IP
-4. SSL: Enable "Let's Encrypt" (auto-renews)
-
-### EasyPanel Subdomain (free)
-
-Format: `service-project.server.easypanel.host`
-SSL included automatically.
-
-## 6. Auto-Deploy
-
-### GitHub Webhook
-
-1. Service > Settings > Enable "Auto Deploy"
-2. EasyPanel generates webhook URL
-3. GitHub repo > Settings > Webhooks > Add webhook
-4. Payload URL: (from EasyPanel)
-5. Content type: application/json
-6. Events: Push events only
-7. Branch filter: main
-
-Pushes to `main` now trigger automatic builds.
-
-## 7. Health Checks
-
-### API Health Check
-
-```
-Path: /health
-Port: 8080
-Interval: 30s
-Timeout: 5s
-Retries: 3
-```
-
-.NET endpoint:
-```csharp
-app.MapGet("/health", () => Results.Ok(new { status = "healthy" }));
-```
-
-### Web Health Check
-
-```
-Path: /api/health
-Port: 3000
-Interval: 30s
-```
-
-Next.js route handler:
-```typescript
-// app/api/health/route.ts
-export function GET() {
-  return Response.json({ status: 'healthy' });
-}
-```
-
-## 8. Monitoring
-
-### Logs
-
-EasyPanel Dashboard > Service > Logs (real-time streaming)
-
-### Resource Usage
-
-EasyPanel Dashboard > Service > Metrics (CPU, Memory, Network)
-
-### Recommended VPS Sizing
-
-| Workload | RAM | CPU | Storage |
-|----------|-----|-----|---------|
-| Dev/MVP | 2GB | 1 vCPU | 40GB |
-| Small prod | 4GB | 2 vCPU | 80GB |
-| Medium prod | 8GB | 4 vCPU | 160GB |
-
-## Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| Build fails | Check Dockerfile paths, ensure multi-stage layers correct |
-| Port conflict | Verify service ports don't overlap |
-| SSL not working | Wait 5 min for Let's Encrypt propagation, check DNS |
-| Auto-deploy not triggering | Verify webhook URL and branch filter |
-| Container OOM | Increase VPS RAM or optimize app memory usage |

package/stacks/nextjs-supabase/.morph/docs/supabase-mcp-setup.md

@@ -1,247 +0,0 @@
-# Supabase MCP Server Setup Guide
-
-> 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*