@polymorphism-tech/morph-spec 3.0.0 → 3.1.0

package/stacks/nextjs-supabase/.morph/standards/easypanel-deploy.md

@@ -0,0 +1,191 @@
+# EasyPanel Deployment Standard
+
+> Stack: Next.js 15 + Supabase + .NET Backend
+
+## Core Rules
+
+- ALWAYS use multi-stage Docker builds for minimal image size
+- ALWAYS configure health checks for zero-downtime deploys
+- NEVER hardcode secrets in Dockerfiles -- use EasyPanel environment variables
+- ALWAYS use `.dockerignore` to exclude node_modules, .git, .env files
+- SSL is automatic via Let's Encrypt -- no manual certificate management
+
+## .NET 10 Dockerfile
+
+```dockerfile
+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
+
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
+WORKDIR /app
+RUN adduser --disabled-password --gecos "" appuser
+USER appuser
+COPY --from=build /app/publish .
+ENV ASPNETCORE_URLS=http://+:8080
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:8080/health || exit 1
+ENTRYPOINT ["dotnet", "MyApp.Api.dll"]
+```
+
+## Next.js Standalone Dockerfile
+
+```dockerfile
+FROM node:22-alpine AS base
+
+FROM base AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV=production 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 HOSTNAME="0.0.0.0"
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
+CMD ["node", "server.js"]
+```
+
+Required: `output: "standalone"` in `next.config.ts`.
+
+## .dockerignore
+
+```
+node_modules
+.next
+.git
+.env*
+*.md
+.vscode
+coverage
+test
+__tests__
+```
+
+## EasyPanel Service Config
+
+| Setting | .NET Backend | Next.js Frontend |
+|---------|-------------|-----------------|
+| Source | GitHub | GitHub |
+| Build method | Dockerfile | Dockerfile |
+| Dockerfile path | `./backend/Dockerfile` | `./frontend/Dockerfile` |
+| Port | 8080 | 3000 |
+| Domain | api.example.com | app.example.com |
+
+### GitHub Integration
+
+1. Generate GitHub PAT with `repo` scope
+2. EasyPanel: Settings > GitHub > Add token
+3. Select repository and branch
+4. Enable "Auto Deploy" for webhook-triggered deploys
+
+### Domain and SSL
+
+DNS setup (CNAME to EasyPanel server):
+```
+app.example.com  CNAME  your-server.easypanel.host
+api.example.com  CNAME  your-server.easypanel.host
+```
+
+SSL via Let's Encrypt is automatic. Force HTTPS enabled by default.
+
+## Environment Variables
+
+### .NET Backend
+
+```env
+ASPNETCORE_ENVIRONMENT=Production
+ASPNETCORE_URLS=http://+:8080
+ConnectionStrings__DefaultConnection=Host=...;Database=...;Username=...;Password=...
+Supabase__Url=https://xxx.supabase.co
+Supabase__ServiceRoleKey=eyJ...
+Supabase__JwtSecret=your-jwt-secret
+```
+
+### Next.js Frontend
+
+```env
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+NEXT_PUBLIC_API_URL=https://api.example.com
+```
+
+## Health Check Endpoints
+
+```csharp
+// .NET: Program.cs
+builder.Services.AddHealthChecks()
+    .AddNpgSql(connectionString, name: "database");
+app.MapHealthChecks("/health");
+```
+
+```ts
+// Next.js: app/api/health/route.ts
+export async function GET() {
+  return Response.json({ status: "healthy", timestamp: new Date().toISOString() });
+}
+```
+
+## Zero-Downtime Deploys
+
+EasyPanel uses Docker HEALTHCHECK to determine container readiness:
+
+1. New container starts alongside old container
+2. Health check passes after start-period + retries
+3. Traffic shifts to new container
+4. Old container stopped
+
+| HEALTHCHECK Param | Value | Purpose |
+|-------------------|-------|---------|
+| `--interval` | 30s | Time between checks |
+| `--timeout` | 5s | Max response wait |
+| `--start-period` | 10s | Startup grace period |
+| `--retries` | 3 | Failures before unhealthy |
+
+## Monitoring
+
+- **Logs**: Real-time in EasyPanel UI
+- **Metrics**: CPU, memory, network via dashboard
+- **Restart**: Auto-restart on crash (default)
+
+Structured logging:
+
+```csharp
+// .NET: Serilog with JSON output
+builder.Host.UseSerilog((ctx, cfg) => cfg
+    .ReadFrom.Configuration(ctx.Configuration)
+    .WriteTo.Console(new JsonFormatter()));
+```
+
+```ts
+// Next.js: pino
+import pino from "pino";
+const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
+```
+
+## Deployment Checklist
+
+| Step | Action |
+|------|--------|
+| 1 | Verify `output: "standalone"` in next.config.ts |
+| 2 | Test Docker build locally |
+| 3 | Test health endpoint |
+| 4 | Configure env vars in EasyPanel |
+| 5 | Set up custom domain + DNS |
+| 6 | Verify SSL certificate |
+| 7 | Enable auto-deploy from GitHub |
+| 8 | Push to main, verify deployment |

package/stacks/nextjs-supabase/.morph/standards/nextjs-patterns.md

@@ -0,0 +1,193 @@
+# Next.js 15 Patterns Standard
+
+> Stack: Next.js 15 + Supabase + .NET Backend
+
+## Core Rules
+
+- ALWAYS use App Router (not Pages Router)
+- Default to Server Components -- add `'use client'` only when needed
+- ALWAYS colocate loading.tsx and error.tsx with page.tsx
+- NEVER call Supabase directly from client -- use Route Handlers as BFF
+- ALWAYS validate inputs with Zod on both client and server
+- Use TypeScript strict mode (`"strict": true`)
+
+## Server vs Client Components
+
+| Aspect | Server Component (default) | Client Component (`'use client'`) |
+|--------|---------------------------|-----------------------------------|
+| Renders | Server only | Server SSR + Client hydration |
+| Access to | DB, env vars, fs, async/await | Browser APIs, useState, useEffect, events |
+| Bundle | Not included | Included in JS bundle |
+| Use when | Data fetching, static content | Interactivity, forms, real-time |
+
+Decision: Need useState/useEffect/onClick/browser APIs? Client Component. Otherwise Server Component.
+
+## File-Based Routing
+
+```
+app/
+  layout.tsx              # Root layout
+  page.tsx                # / (home)
+  loading.tsx / error.tsx # Loading UI / Error boundary
+  not-found.tsx           # 404
+  dashboard/
+    layout.tsx            # Nested layout
+    page.tsx              # /dashboard
+    loading.tsx
+  api/documents/
+    route.ts              # GET/POST /api/documents
+    [id]/route.ts         # GET/PUT/DELETE /api/documents/:id
+```
+
+## Layout and Error Boundaries
+
+```tsx
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <html lang="en"><body><Providers>{children}</Providers></body></html>;
+}
+
+// loading.tsx
+export default function Loading() { return <div className="animate-pulse">Loading...</div>; }
+
+// error.tsx — MUST be 'use client'
+'use client';
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+  return <div><h2>Something went wrong</h2><button onClick={reset}>Try again</button></div>;
+}
+```
+
+## Route Handlers (BFF Pattern)
+
+```ts
+// app/api/documents/route.ts
+import { createClient } from "@/lib/supabase/server";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+
+const CreateSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().min(1),
+});
+
+export async function GET() {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  const { data, error } = await supabase.from("documents").select("*");
+  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
+  return NextResponse.json(data);
+}
+
+export async function POST(request: Request) {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  const parsed = CreateSchema.safeParse(await request.json());
+  if (!parsed.success) return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
+  const { data, error } = await supabase
+    .from("documents").insert({ ...parsed.data, user_id: user.id }).select().single();
+  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
+  return NextResponse.json(data, { status: 201 });
+}
+```
+
+## React Query + Supabase
+
+```tsx
+// providers/query-provider.tsx
+'use client';
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useState } from "react";
+
+export function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [client] = useState(() => new QueryClient({
+    defaultOptions: { queries: { staleTime: 60_000, retry: 1 } },
+  }));
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+}
+```
+
+```tsx
+// hooks/use-documents.ts
+export function useDocuments() {
+  return useQuery({
+    queryKey: ["documents"],
+    queryFn: async () => {
+      const res = await fetch("/api/documents");
+      if (!res.ok) throw new Error("Failed to fetch");
+      return res.json();
+    },
+  });
+}
+
+export function useCreateDocument() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: async (data: { title: string; content: string }) => {
+      const res = await fetch("/api/documents", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(data),
+      });
+      if (!res.ok) throw new Error("Failed to create");
+      return res.json();
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["documents"] }),
+  });
+}
+```
+
+## Form Handling (react-hook-form + Zod)
+
+```tsx
+'use client';
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+
+const schema = z.object({
+  title: z.string().min(1, "Required").max(200),
+  content: z.string().min(1, "Required"),
+});
+
+export function DocumentForm() {
+  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<z.infer<typeof schema>>({
+    resolver: zodResolver(schema),
+  });
+  const create = useCreateDocument();
+  return (
+    <form onSubmit={handleSubmit((data) => create.mutateAsync(data))}>
+      <input {...register("title")} />
+      {errors.title && <span>{errors.title.message}</span>}
+      <textarea {...register("content")} />
+      {errors.content && <span>{errors.content.message}</span>}
+      <button type="submit" disabled={isSubmitting}>Save</button>
+    </form>
+  );
+}
+```
+
+## shadcn/ui
+
+Install: `npx shadcn@latest init` then `npx shadcn@latest add button input card dialog form`.
+Components are copied to `components/ui/` -- NOT an npm dependency, your code to customize.
+
+## TypeScript Strict Patterns
+
+| Pattern | Approach |
+|---------|----------|
+| API responses | Zod schema + `z.infer<typeof schema>` |
+| Props | Explicit interface, no `any` |
+| Event handlers | `React.ChangeEvent<HTMLInputElement>` |
+| Null safety | `?.` over type assertions, `if (!data) return null` |
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `'use client'` on every component | Default to Server Components | Unnecessary JS bundle size |
+| Direct Supabase from client | Route Handler `/api/*` as BFF | Exposes queries, harder to secure |
+| `any` for API responses | Zod schema + infer | No runtime safety |
+| Missing loading.tsx | Colocate with page.tsx | Blank page during load |
+| `useEffect` for data fetching | React Query `useQuery` | No caching, race conditions |
+| Form validation on submit only | Zod resolver + react-hook-form | Delayed error feedback |
+| shadcn as npm package | `npx shadcn@latest add` | Copy-paste system, not a dependency |

package/stacks/nextjs-supabase/.morph/standards/supabase-auth.md

@@ -0,0 +1,171 @@
+# Supabase Authentication Standard
+
+> 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 |