@polymorphism-tech/morph-spec 3.2.0 → 4.3.0

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

@@ -1,335 +0,0 @@
-# Next.js + Supabase Frontend
-
-> **Layer:** 2 | **Load:** on-keyword | **Keywords:** nextjs, supabase, ssr, auth, react-query, shadcn, tailwind, middleware
-
-## Identity
-
-Frontend specialist for Next.js App Router with Supabase. Implements @supabase/ssr for server and browser clients, auth middleware for route protection, React Query for data fetching with Supabase, shadcn/ui components with Tailwind CSS, and Realtime subscriptions.
-
-## Domains
-
-- auth-ui
-- data-fetching
-- realtime
-- components
-
-## Standards
-
-- css-naming.md -- Tailwind utility class ordering conventions
-- architecture.md -- Server vs Client component boundaries
-
-## Patterns
-
-### @supabase/ssr Client Setup
-
-```typescript
-// lib/supabase/client.ts (Browser client)
-import { createBrowserClient } from "@supabase/ssr";
-import type { Database } from "@/types/database";
-
-export function createClient() {
-  return createBrowserClient<Database>(
-    process.env.NEXT_PUBLIC_SUPABASE_URL!,
-    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
-  );
-}
-```
-
-```typescript
-// lib/supabase/server.ts (Server client)
-import { createServerClient } from "@supabase/ssr";
-import { cookies } from "next/headers";
-import type { Database } from "@/types/database";
-
-export async function createServerSupabaseClient() {
-  const cookieStore = await cookies();
-
-  return createServerClient<Database>(
-    process.env.NEXT_PUBLIC_SUPABASE_URL!,
-    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
-    {
-      cookies: {
-        getAll() {
-          return cookieStore.getAll();
-        },
-        setAll(cookiesToSet) {
-          try {
-            cookiesToSet.forEach(({ name, value, options }) =>
-              cookieStore.set(name, value, options)
-            );
-          } catch {
-            // The `setAll` method is called from a Server Component
-            // if middleware refreshes the session. Ignore in that context.
-          }
-        },
-      },
-    }
-  );
-}
-```
-
-### Auth Middleware
-
-```typescript
-// middleware.ts
-import { createServerClient } from "@supabase/ssr";
-import { NextResponse, type NextRequest } from "next/server";
-
-const publicRoutes = ["/", "/login", "/signup", "/auth/callback"];
-
-export async function middleware(request: NextRequest) {
-  let response = 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 }) =>
-            request.cookies.set(name, value)
-          );
-          response = NextResponse.next({ request });
-          cookiesToSet.forEach(({ name, value, options }) =>
-            response.cookies.set(name, value, options)
-          );
-        },
-      },
-    }
-  );
-
-  const {
-    data: { user },
-  } = await supabase.auth.getUser();
-
-  const isPublicRoute = publicRoutes.some((route) =>
-    request.nextUrl.pathname.startsWith(route)
-  );
-
-  if (!user && !isPublicRoute) {
-    const url = request.nextUrl.clone();
-    url.pathname = "/login";
-    url.searchParams.set("redirectTo", request.nextUrl.pathname);
-    return NextResponse.redirect(url);
-  }
-
-  return response;
-}
-
-export const config = {
-  matcher: ["/((?!_next/static|_next/image|favicon.ico|api/health).*)"],
-};
-```
-
-### Auth Callback Route
-
-```typescript
-// app/auth/callback/route.ts
-import { createServerSupabaseClient } 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 createServerSupabaseClient();
-    const { error } = await supabase.auth.exchangeCodeForSession(code);
-    if (!error) {
-      return NextResponse.redirect(`${origin}${next}`);
-    }
-  }
-
-  return NextResponse.redirect(`${origin}/login?error=auth_failed`);
-}
-```
-
-### React Query + Supabase
-
-```typescript
-// hooks/use-documents.ts
-"use client";
-import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
-import { createClient } from "@/lib/supabase/client";
-import type { Document, CreateDocumentInput } from "@/types/database";
-
-const supabase = createClient();
-
-export function useDocuments(page = 1, pageSize = 10) {
-  return useQuery({
-    queryKey: ["documents", page, pageSize],
-    queryFn: async () => {
-      const from = (page - 1) * pageSize;
-      const to = from + pageSize - 1;
-
-      const { data, error, count } = await supabase
-        .from("documents")
-        .select("*", { count: "exact" })
-        .order("created_at", { ascending: false })
-        .range(from, to);
-
-      if (error) throw error;
-      return { items: data as Document[], totalCount: count ?? 0, page, pageSize };
-    },
-  });
-}
-
-export function useCreateDocument() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: async (input: CreateDocumentInput) => {
-      const { data, error } = await supabase
-        .from("documents")
-        .insert(input)
-        .select()
-        .single();
-
-      if (error) throw error;
-      return data as Document;
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["documents"] });
-    },
-  });
-}
-```
-
-### Form with react-hook-form + zod
-
-```typescript
-// components/document-form.tsx
-"use client";
-import { useForm } from "react-hook-form";
-import { zodResolver } from "@hookform/resolvers/zod";
-import { z } from "zod";
-import { Button } from "@/components/ui/button";
-import { Input } from "@/components/ui/input";
-import { Textarea } from "@/components/ui/textarea";
-import { useCreateDocument } from "@/hooks/use-documents";
-
-const schema = z.object({
-  title: z.string().min(1, "Title is required").max(200),
-  content: z.string().min(1, "Content is required"),
-});
-
-type FormData = z.infer<typeof schema>;
-
-export function DocumentForm({ onSuccess }: { onSuccess?: () => void }) {
-  const { register, handleSubmit, formState: { errors }, reset } = useForm<FormData>({
-    resolver: zodResolver(schema),
-  });
-
-  const createDocument = useCreateDocument();
-
-  const onSubmit = async (data: FormData) => {
-    await createDocument.mutateAsync(data);
-    reset();
-    onSuccess?.();
-  };
-
-  return (
-    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
-      <div>
-        <Input placeholder="Document title" {...register("title")} />
-        {errors.title && <p className="text-sm text-destructive mt-1">{errors.title.message}</p>}
-      </div>
-      <div>
-        <Textarea placeholder="Content..." rows={6} {...register("content")} />
-        {errors.content && <p className="text-sm text-destructive mt-1">{errors.content.message}</p>}
-      </div>
-      <Button type="submit" disabled={createDocument.isPending}>
-        {createDocument.isPending ? "Creating..." : "Create Document"}
-      </Button>
-    </form>
-  );
-}
-```
-
-### Realtime Subscription Hook
-
-```typescript
-// hooks/use-realtime.ts
-"use client";
-import { useEffect } from "react";
-import { useQueryClient } from "@tanstack/react-query";
-import { createClient } from "@/lib/supabase/client";
-import type { RealtimePostgresChangesPayload } from "@supabase/supabase-js";
-
-export function useRealtimeSubscription<T extends Record<string, unknown>>(
-  table: string,
-  queryKey: string[]
-) {
-  const queryClient = useQueryClient();
-  const supabase = createClient();
-
-  useEffect(() => {
-    const channel = supabase
-      .channel(`${table}-changes`)
-      .on<T>(
-        "postgres_changes",
-        { event: "*", schema: "public", table },
-        (payload: RealtimePostgresChangesPayload<T>) => {
-          queryClient.invalidateQueries({ queryKey });
-        }
-      )
-      .subscribe();
-
-    return () => {
-      supabase.removeChannel(channel);
-    };
-  }, [table, queryKey, queryClient, supabase]);
-}
-
-// Usage in component:
-// useRealtimeSubscription<Document>("documents", ["documents"]);
-```
-
-### Server Component Data Fetching
-
-```typescript
-// app/dashboard/page.tsx
-import { createServerSupabaseClient } from "@/lib/supabase/server";
-import { DocumentList } from "@/components/document-list";
-
-export default async function DashboardPage() {
-  const supabase = await createServerSupabaseClient();
-  const { data: user } = await supabase.auth.getUser();
-
-  const { data: documents } = await supabase
-    .from("documents")
-    .select("*")
-    .order("created_at", { ascending: false })
-    .limit(20);
-
-  return (
-    <main className="container mx-auto py-8">
-      <h1 className="text-2xl font-bold mb-6">
-        Welcome, {user.user?.email}
-      </h1>
-      <DocumentList initialDocuments={documents ?? []} />
-    </main>
-  );
-}
-```
-
-## Checklist
-
-- [ ] @supabase/ssr used (not @supabase/auth-helpers-nextjs)
-- [ ] Server and browser clients in separate files
-- [ ] Middleware refreshes session on every request
-- [ ] Public routes excluded from auth check
-- [ ] Auth callback route handles code exchange
-- [ ] React Query configured with QueryClientProvider
-- [ ] Forms validated with zod schemas
-- [ ] Realtime subscriptions clean up on unmount
-- [ ] Server Components fetch data directly (no useEffect)
-- [ ] Environment variables: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

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

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

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