@polymorphism-tech/morph-spec 3.0.1 → 3.2.0

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

@@ -0,0 +1,244 @@
+# .NET + Supabase Backend
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** dotnet, supabase, npgsql, dapper, jwt, minimal-api, postgresql
+
+## Identity
+
+Backend specialist for .NET Minimal API with Supabase (PostgreSQL). Uses Npgsql for connections, Dapper for data access with records, JWT middleware for Supabase Auth token validation, and typed Minimal API endpoints. No EF Core -- direct SQL with Dapper for maximum control over Supabase's PostgreSQL.
+
+## Domains
+
+- data-access
+- auth-middleware
+- api-endpoints
+
+## Standards
+
+- coding.md -- C# naming, sealed classes, CancellationToken, Result pattern
+- architecture.md -- Layer boundaries (API -> Application -> Domain)
+
+## Patterns
+
+### Npgsql Connection Setup
+
+```csharp
+// Program.cs
+builder.Services.AddSingleton<NpgsqlDataSource>(sp =>
+{
+    var connectionString = builder.Configuration.GetConnectionString("Supabase")
+        ?? throw new InvalidOperationException("Supabase connection string not configured");
+    var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
+    dataSourceBuilder.UseVector(); // pgvector support
+    return dataSourceBuilder.Build();
+});
+
+// appsettings.json
+{
+  "ConnectionStrings": {
+    "Supabase": "Host=db.xxx.supabase.co;Port=5432;Database=postgres;Username=postgres;Password=${DB_PASSWORD};SSL Mode=Require;Trust Server Certificate=true"
+  }
+}
+```
+
+### Dapper Queries with Records
+
+```csharp
+namespace MyApp.Infrastructure.Repositories;
+
+public sealed class DocumentRepository(NpgsqlDataSource dataSource) : IDocumentRepository
+{
+    public async Task<DocumentDto?> GetByIdAsync(Guid id, CancellationToken ct = default)
+    {
+        await using var connection = await dataSource.OpenConnectionAsync(ct);
+        return await connection.QueryFirstOrDefaultAsync<DocumentDto>(
+            """
+            SELECT id, title, content, user_id AS UserId, created_at AS CreatedAt
+            FROM documents
+            WHERE id = @Id
+            """,
+            new { Id = id });
+    }
+
+    public async Task<PagedResult<DocumentDto>> GetPagedAsync(
+        PaginationQuery query,
+        Guid userId,
+        CancellationToken ct = default)
+    {
+        await using var connection = await dataSource.OpenConnectionAsync(ct);
+
+        var count = await connection.ExecuteScalarAsync<int>(
+            "SELECT count(*) FROM documents WHERE user_id = @UserId",
+            new { UserId = userId });
+
+        var items = await connection.QueryAsync<DocumentDto>(
+            """
+            SELECT id, title, content, user_id AS UserId, created_at AS CreatedAt
+            FROM documents
+            WHERE user_id = @UserId
+            ORDER BY created_at DESC
+            LIMIT @PageSize OFFSET @Offset
+            """,
+            new { UserId = userId, query.PageSize, Offset = (query.Page - 1) * query.PageSize });
+
+        return new PagedResult<DocumentDto>(items.ToList(), count, query.Page, query.PageSize);
+    }
+
+    public async Task<Guid> CreateAsync(CreateDocumentRequest request, Guid userId, CancellationToken ct = default)
+    {
+        await using var connection = await dataSource.OpenConnectionAsync(ct);
+        return await connection.ExecuteScalarAsync<Guid>(
+            """
+            INSERT INTO documents (title, content, user_id)
+            VALUES (@Title, @Content, @UserId)
+            RETURNING id
+            """,
+            new { request.Title, request.Content, UserId = userId });
+    }
+}
+```
+
+### JWT Middleware Setup (Supabase Auth)
+
+```csharp
+// Program.cs
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddJwtBearer(options =>
+    {
+        var supabaseUrl = builder.Configuration["Supabase:Url"]
+            ?? throw new InvalidOperationException("Supabase:Url not configured");
+        var jwtSecret = builder.Configuration["Supabase:JwtSecret"]
+            ?? throw new InvalidOperationException("Supabase:JwtSecret not configured");
+
+        options.TokenValidationParameters = new TokenValidationParameters
+        {
+            ValidateIssuer = true,
+            ValidIssuer = $"{supabaseUrl}/auth/v1",
+            ValidateAudience = true,
+            ValidAudience = "authenticated",
+            ValidateIssuerSigningKey = true,
+            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(jwtSecret)),
+            ValidateLifetime = true,
+            ClockSkew = TimeSpan.FromSeconds(30)
+        };
+    });
+
+builder.Services.AddAuthorization();
+app.UseAuthentication();
+app.UseAuthorization();
+```
+
+### User ID Extraction
+
+```csharp
+// Extension method for ClaimsPrincipal
+public static class ClaimsPrincipalExtensions
+{
+    public static Guid GetUserId(this ClaimsPrincipal user)
+    {
+        var sub = user.FindFirstValue(ClaimTypes.NameIdentifier)
+            ?? throw new UnauthorizedAccessException("User ID claim not found");
+        return Guid.Parse(sub);
+    }
+}
+```
+
+### Minimal API Endpoints
+
+```csharp
+namespace MyApp.Api.Endpoints;
+
+public static class DocumentEndpoints
+{
+    public static void MapDocumentEndpoints(this WebApplication app)
+    {
+        var group = app.MapGroup("/api/documents")
+            .WithTags("Documents")
+            .RequireAuthorization();
+
+        group.MapGet("/", GetAllAsync);
+        group.MapGet("/{id:guid}", GetByIdAsync);
+        group.MapPost("/", CreateAsync);
+        group.MapPut("/{id:guid}", UpdateAsync);
+        group.MapDelete("/{id:guid}", DeleteAsync);
+    }
+
+    private static async Task<IResult> GetAllAsync(
+        [AsParameters] PaginationQuery query,
+        ClaimsPrincipal user,
+        IDocumentService service,
+        CancellationToken ct)
+    {
+        var userId = user.GetUserId();
+        var result = await service.GetPagedAsync(query, userId, ct);
+        return Results.Ok(result);
+    }
+
+    private static async Task<IResult> CreateAsync(
+        CreateDocumentRequest request,
+        ClaimsPrincipal user,
+        IDocumentService service,
+        CancellationToken ct)
+    {
+        var userId = user.GetUserId();
+        var result = await service.CreateAsync(request, userId, ct);
+        return result.IsSuccess
+            ? Results.Created($"/api/documents/{result.Value.Id}", result.Value)
+            : Results.BadRequest(result.Error);
+    }
+}
+```
+
+### Supabase Client Wrapper (for Storage/Auth Admin)
+
+```csharp
+namespace MyApp.Infrastructure.Supabase;
+
+public sealed class SupabaseAdmin(HttpClient httpClient, IOptions<SupabaseOptions> options)
+{
+    private readonly string _serviceKey = options.Value.ServiceRoleKey;
+
+    public async Task<string> UploadFileAsync(
+        string bucket,
+        string path,
+        Stream content,
+        string contentType,
+        CancellationToken ct = default)
+    {
+        using var request = new HttpRequestMessage(HttpMethod.Post,
+            $"{options.Value.Url}/storage/v1/object/{bucket}/{path}");
+        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _serviceKey);
+        request.Headers.Add("apikey", _serviceKey);
+        request.Content = new StreamContent(content);
+        request.Content.Headers.ContentType = new MediaTypeHeaderValue(contentType);
+
+        var response = await httpClient.SendAsync(request, ct);
+        response.EnsureSuccessStatusCode();
+
+        var result = await response.Content.ReadFromJsonAsync<StorageUploadResult>(ct);
+        return $"{options.Value.Url}/storage/v1/object/public/{bucket}/{result?.Key}";
+    }
+}
+
+public sealed record SupabaseOptions
+{
+    public required string Url { get; init; }
+    public required string AnonKey { get; init; }
+    public required string ServiceRoleKey { get; init; }
+    public required string JwtSecret { get; init; }
+}
+```
+
+## Checklist
+
+- [ ] NpgsqlDataSource registered as Singleton (connection pooling)
+- [ ] Dapper queries use parameterized SQL (never string interpolation)
+- [ ] JWT middleware validates issuer, audience, signing key, and lifetime
+- [ ] service_role key stored in environment variables (not appsettings)
+- [ ] All async methods accept CancellationToken
+- [ ] All DTOs are records (not classes)
+- [ ] Endpoints use RequireAuthorization()
+- [ ] User ID extracted from JWT claims (not request body)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

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

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