@polymorphism-tech/morph-spec 3.0.1 → 3.2.0

package/stacks/nextjs-supabase/.claude/skills/level-2-domains/infrastructure/easypanel-deployer.md

@@ -0,0 +1,189 @@
+# EasyPanel Deployer
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** easypanel, deploy, docker, ssl, domain, vps, container
+
+## Identity
+
+Infrastructure and deployment specialist for EasyPanel on VPS. Builds multi-stage Dockerfiles for .NET API and Next.js frontend, configures GitHub integration for auto-deploy, manages SSL certificates, and sets up health check endpoints.
+
+## Domains
+
+- deployment
+- docker
+- ssl
+- monitoring
+
+## Standards
+
+- architecture.md -- Layer separation reflected in Docker build stages
+- coding.md -- Health check endpoint patterns
+
+## Patterns
+
+### Dockerfile Multi-Stage (.NET API)
+
+```dockerfile
+# Stage 1: Build
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY *.csproj .
+RUN dotnet restore
+COPY . .
+RUN dotnet publish -c Release -o /app/publish --no-restore
+
+# Stage 2: Runtime
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
+WORKDIR /app
+COPY --from=build /app/publish .
+ENV ASPNETCORE_URLS=http://+:8080
+ENV ASPNETCORE_ENVIRONMENT=Production
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:8080/health || exit 1
+ENTRYPOINT ["dotnet", "Api.dll"]
+```
+
+### Dockerfile Multi-Stage (Next.js)
+
+```dockerfile
+# Stage 1: Dependencies
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+# Stage 2: Build
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+# Stage 3: Runtime
+FROM node:22-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+USER nextjs
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+CMD ["node", "server.js"]
+```
+
+### EasyPanel GitHub Integration
+
+```yaml
+# EasyPanel service configuration (via UI or API)
+# 1. Connect GitHub repository
+# 2. Configure build settings:
+Service:
+  name: my-app-api
+  source: github
+  repository: org/repo
+  branch: main
+  dockerfile: ./backend/Dockerfile
+  port: 8080
+  env:
+    - SUPABASE_URL=https://xxx.supabase.co
+    - SUPABASE_SERVICE_KEY=${SECRET}
+    - ASPNETCORE_ENVIRONMENT=Production
+
+# Auto-deploy: triggers on push to configured branch
+# Rollback: EasyPanel keeps previous image for instant rollback
+```
+
+### SSL Setup
+
+```
+# EasyPanel handles SSL automatically via Let's Encrypt
+# Configuration steps:
+# 1. Add custom domain in EasyPanel service settings
+# 2. Point DNS A record to VPS IP
+# 3. EasyPanel auto-provisions SSL certificate
+# 4. Auto-renewal handled by EasyPanel
+
+# Force HTTPS redirect (handled by EasyPanel reverse proxy)
+# No application-level SSL configuration needed
+
+# Multi-domain setup:
+# - api.myapp.com -> API service (port 8080)
+# - myapp.com     -> Web service (port 3000)
+```
+
+### Health Checks
+
+```csharp
+// .NET API health check endpoint
+// Program.cs
+builder.Services.AddHealthChecks()
+    .AddNpgSql(connectionString, name: "supabase-db")
+    .AddUrlGroup(new Uri($"{supabaseUrl}/rest/v1/"), name: "supabase-api");
+
+app.MapHealthChecks("/health", new HealthCheckOptions
+{
+    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
+});
+
+app.MapGet("/health/ready", () => Results.Ok(new { status = "ready", timestamp = DateTime.UtcNow }));
+app.MapGet("/health/live", () => Results.Ok(new { status = "alive" }));
+```
+
+```typescript
+// Next.js health check (app/api/health/route.ts)
+export async function GET() {
+  return Response.json({
+    status: "healthy",
+    timestamp: new Date().toISOString(),
+    version: process.env.npm_package_version ?? "unknown",
+  });
+}
+```
+
+### Docker Compose (Local Development)
+
+```yaml
+services:
+  api:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile
+    ports: ["8080:8080"]
+    environment:
+      - SUPABASE_URL=http://supabase-kong:8000
+      - SUPABASE_SERVICE_KEY=${SERVICE_ROLE_KEY}
+      - ASPNETCORE_ENVIRONMENT=Development
+    depends_on: [supabase-db]
+
+  web:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile
+    ports: ["3000:3000"]
+    environment:
+      - NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
+      - NEXT_PUBLIC_SUPABASE_ANON_KEY=${ANON_KEY}
+      - NEXT_PUBLIC_API_URL=http://localhost:8080
+```
+
+## Checklist
+
+- [ ] Dockerfiles use multi-stage builds (small final images)
+- [ ] Next.js uses standalone output mode
+- [ ] .dockerignore excludes node_modules, .next, .git, .env*
+- [ ] Health check endpoints configured
+- [ ] Environment variables set in EasyPanel (not hardcoded)
+- [ ] SSL certificates provisioned via EasyPanel
+- [ ] DNS records point to VPS IP
+- [ ] Auto-deploy configured on main branch
+- [ ] Resource limits set (CPU/memory) in EasyPanel
+- [ ] Logs accessible via EasyPanel dashboard
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/stacks/nextjs-supabase/.claude/skills/level-2-domains/integrations/supabase-expert.md

@@ -0,0 +1,170 @@
+# Supabase Expert
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** supabase, postgres, rls, auth, storage, realtime, pgvector, migration
+
+## Identity
+
+Database and backend-as-a-service specialist for Supabase. Designs PostgreSQL schemas, Row Level Security policies, Auth flows, Storage buckets, Realtime subscriptions, and pgvector embeddings. Ensures all data access goes through RLS-protected paths.
+
+## Domains
+
+- database-design
+- auth-flows
+- rls-policies
+- storage
+- vector-search
+- realtime
+
+## Standards
+
+- coding.md -- C# naming and async patterns for backend consumers
+- architecture.md -- Layer boundaries when Supabase replaces traditional ORM
+
+## Patterns
+
+### RLS Policy Creation
+
+```sql
+-- Enable RLS on table
+alter table public.documents enable row level security;
+
+-- Users can only read their own documents
+create policy "Users read own documents"
+  on public.documents for select
+  using (auth.uid() = user_id);
+
+-- Users can insert documents for themselves
+create policy "Users insert own documents"
+  on public.documents for insert
+  with check (auth.uid() = user_id);
+
+-- Users can update their own documents
+create policy "Users update own documents"
+  on public.documents for update
+  using (auth.uid() = user_id)
+  with check (auth.uid() = user_id);
+
+-- Users can delete their own documents
+create policy "Users delete own documents"
+  on public.documents for delete
+  using (auth.uid() = user_id);
+
+-- Service role bypasses RLS (for .NET API with service_role key)
+-- No policy needed: service_role key skips RLS automatically
+```
+
+### Supabase Auth Setup
+
+```sql
+-- Auth is built-in. Configure providers via Supabase Dashboard or config.toml.
+-- Key tables: auth.users (managed), public.profiles (custom)
+
+-- Auto-create profile on signup via trigger
+create or replace function public.handle_new_user()
+returns trigger as $$
+begin
+  insert into public.profiles (id, email, display_name, avatar_url)
+  values (
+    new.id,
+    new.email,
+    coalesce(new.raw_user_meta_data ->> 'full_name', split_part(new.email, '@', 1)),
+    new.raw_user_meta_data ->> 'avatar_url'
+  );
+  return new;
+end;
+$$ language plpgsql security definer;
+
+create trigger on_auth_user_created
+  after insert on auth.users
+  for each row execute function public.handle_new_user();
+```
+
+### Storage Bucket Configuration
+
+```sql
+-- Create a private bucket (RLS-protected)
+insert into storage.buckets (id, name, public, file_size_limit, allowed_mime_types)
+values (
+  'documents',
+  'documents',
+  false,
+  5242880, -- 5MB
+  array['application/pdf', 'image/png', 'image/jpeg']
+);
+
+-- Storage RLS: users access their own folder
+create policy "Users manage own files"
+  on storage.objects for all
+  using (bucket_id = 'documents' and (storage.foldername(name))[1] = auth.uid()::text)
+  with check (bucket_id = 'documents' and (storage.foldername(name))[1] = auth.uid()::text);
+```
+
+### pgvector Queries
+
+```sql
+-- Enable extension
+create extension if not exists vector;
+
+-- Table with embedding column
+create table public.document_chunks (
+  id bigint generated always as identity primary key,
+  document_id uuid references public.documents(id) on delete cascade,
+  content text not null,
+  embedding vector(1536), -- OpenAI text-embedding-3-small
+  metadata jsonb default '{}'::jsonb,
+  created_at timestamptz default now()
+);
+
+-- HNSW index for fast similarity search
+create index on public.document_chunks
+  using hnsw (embedding vector_cosine_ops)
+  with (m = 16, ef_construction = 64);
+
+-- Similarity search function
+create or replace function match_documents(
+  query_embedding vector(1536),
+  match_threshold float default 0.78,
+  match_count int default 10
+)
+returns table (id bigint, content text, similarity float)
+language sql stable
+as $$
+  select
+    dc.id,
+    dc.content,
+    1 - (dc.embedding <=> query_embedding) as similarity
+  from public.document_chunks dc
+  where 1 - (dc.embedding <=> query_embedding) > match_threshold
+  order by dc.embedding <=> query_embedding
+  limit match_count;
+$$;
+```
+
+### Migration Management
+
+```bash
+# Supabase CLI migration workflow
+supabase migration new create_documents_table  # creates timestamped SQL file
+supabase db push                                # apply migrations to remote
+supabase db reset                               # reset local DB and replay all migrations
+supabase db diff --schema public                # generate migration from schema diff
+
+# Migration file naming: supabase/migrations/{timestamp}_description.sql
+# Always include: CREATE TABLE, indexes, RLS enable, policies
+# Never include: seed data (use supabase/seed.sql)
+```
+
+## Checklist
+
+- [ ] All tables have RLS enabled
+- [ ] Every table has at least one SELECT policy
+- [ ] service_role key used only in backend (never exposed to client)
+- [ ] Storage buckets have file size limits and MIME type restrictions
+- [ ] Auth trigger creates profile on signup
+- [ ] pgvector index type matches query pattern (HNSW for recall, IVFFlat for speed)
+- [ ] Migrations are idempotent (use IF NOT EXISTS)
+- [ ] Foreign keys have ON DELETE behavior defined
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*