@polymorphism-tech/morph-spec 3.0.1 → 3.1.0

package/stacks/nextjs-supabase/.morph/examples/crud-nextjs-supabase/README.md

@@ -0,0 +1,697 @@
+# CRUD App - Next.js + .NET API + Supabase
+
+Complete CRUD application with authentication, Row Level Security, and file uploads.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   Next.js 15 Frontend                       │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │  App Router  │  │  Components  │  │  Supabase Auth   │  │
+│  │  /products   │  │  DataTable   │  │  login/signup    │  │
+│  │  /dashboard  │  │  FileUpload  │  │  session mgmt    │  │
+│  └──────────────┘  └──────────────┘  └──────────────────┘  │
+└────────────────────────────┬────────────────────────────────┘
+                             │ REST API (Bearer JWT)
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    .NET 10 Minimal API                       │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  Endpoints: /api/products, /api/upload, /api/health  │   │
+│  └──────────────────────────────────────────────────────┘   │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │  Dapper      │  │  JWT Auth    │  │  Supabase        │  │
+│  │  Queries     │  │  Middleware  │  │  Storage Client  │  │
+│  └──────────────┘  └──────────────┘  └──────────────────┘  │
+└────────────────────────────┬────────────────────────────────┘
+                             │ Connection String
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Supabase Cloud                            │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │  PostgreSQL  │  │  Auth        │  │  Storage         │  │
+│  │  + RLS       │  │  (GoTrue)    │  │  (S3-compat)     │  │
+│  └──────────────┘  └──────────────┘  └──────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## What It Demonstrates
+
+- Product CRUD with .NET Minimal API + Dapper
+- Supabase Auth (email/password, OAuth)
+- Row Level Security (RLS) policies on PostgreSQL
+- File uploads via Supabase Storage
+- Server-side data fetching with Next.js Server Components
+- JWT validation on .NET API from Supabase-issued tokens
+- Docker Compose for local development
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| **Frontend** | Next.js 15 (App Router, Server Components) |
+| **Backend** | .NET 10 Minimal APIs + Dapper |
+| **Database** | Supabase PostgreSQL (managed) |
+| **Auth** | Supabase Auth (GoTrue) |
+| **Storage** | Supabase Storage |
+| **Deploy** | EasyPanel (VPS) + Supabase Cloud |
+
+## Cost Estimate
+
+| Resource | Tier | Cost/month |
+|----------|------|------------|
+| Supabase | Free (500MB DB, 1GB Storage, 50k MAU) | $0 |
+| VPS (API + Web) | Hetzner/DigitalOcean 2GB | ~$5-6 |
+| Domain | Optional | ~$1 |
+
+**Total**: ~$6/month for MVPs
+
+---
+
+## Code Reference
+
+### Program.cs (Minimal API with JWT + Supabase)
+
+```csharp
+using System.Text;
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.IdentityModel.Tokens;
+using Npgsql;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Supabase JWT validation
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddJwtBearer(options =>
+    {
+        options.TokenValidationParameters = new TokenValidationParameters
+        {
+            ValidateIssuer = true,
+            ValidIssuer = $"{builder.Configuration["Supabase:Url"]}/auth/v1",
+            ValidateAudience = true,
+            ValidAudience = "authenticated",
+            ValidateLifetime = true,
+            ValidateIssuerSigningKey = true,
+            IssuerSigningKey = new SymmetricSecurityKey(
+                Encoding.UTF8.GetBytes(builder.Configuration["Supabase:JwtSecret"]!))
+        };
+    });
+
+builder.Services.AddAuthorization();
+
+// Dapper: register Npgsql connection factory
+builder.Services.AddScoped<NpgsqlConnection>(_ =>
+    new NpgsqlConnection(builder.Configuration["Supabase:DbConnectionString"]));
+
+// CORS for Next.js frontend
+builder.Services.AddCors(options =>
+{
+    options.AddDefaultPolicy(policy =>
+    {
+        policy.WithOrigins(builder.Configuration["Cors:AllowedOrigins"]!.Split(','))
+            .AllowAnyHeader()
+            .AllowAnyMethod()
+            .AllowCredentials();
+    });
+});
+
+var app = builder.Build();
+
+app.UseCors();
+app.UseAuthentication();
+app.UseAuthorization();
+
+// Map endpoint groups
+app.MapProductEndpoints();
+
+app.MapGet("/health", () => Results.Ok(new { status = "healthy" }));
+
+app.Run();
+```
+
+### Endpoints/ProductsEndpoints.cs (CRUD with Dapper)
+
+```csharp
+using System.Security.Claims;
+using Dapper;
+using Npgsql;
+
+public static class ProductsEndpoints
+{
+    public static void MapProductEndpoints(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/api/products")
+            .WithTags("Products")
+            .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(
+        NpgsqlConnection db,
+        ClaimsPrincipal user,
+        int page = 1,
+        int pageSize = 20,
+        string? search = null,
+        CancellationToken ct = default)
+    {
+        var userId = user.FindFirstValue(ClaimTypes.NameIdentifier);
+        var offset = (page - 1) * pageSize;
+
+        const string countSql = """
+            SELECT COUNT(*) FROM products
+            WHERE user_id = @UserId
+            AND (@Search IS NULL OR name ILIKE '%' || @Search || '%')
+            """;
+
+        const string dataSql = """
+            SELECT id, name, description, price, image_url, created_at, updated_at
+            FROM products
+            WHERE user_id = @UserId
+            AND (@Search IS NULL OR name ILIKE '%' || @Search || '%')
+            ORDER BY created_at DESC
+            LIMIT @PageSize OFFSET @Offset
+            """;
+
+        var parameters = new { UserId = userId, Search = search, PageSize = pageSize, Offset = offset };
+
+        await db.OpenAsync(ct);
+        var total = await db.ExecuteScalarAsync<int>(countSql, parameters);
+        var items = await db.QueryAsync<ProductDto>(dataSql, parameters);
+
+        return Results.Ok(new
+        {
+            items,
+            total,
+            page,
+            pageSize,
+            totalPages = (int)Math.Ceiling(total / (double)pageSize)
+        });
+    }
+
+    private static async Task<IResult> GetByIdAsync(
+        Guid id, NpgsqlConnection db, ClaimsPrincipal user, CancellationToken ct = default)
+    {
+        var userId = user.FindFirstValue(ClaimTypes.NameIdentifier);
+        await db.OpenAsync(ct);
+
+        var product = await db.QuerySingleOrDefaultAsync<ProductDto>(
+            "SELECT * FROM products WHERE id = @Id AND user_id = @UserId",
+            new { Id = id, UserId = userId });
+
+        return product is null ? Results.NotFound() : Results.Ok(product);
+    }
+
+    private static async Task<IResult> CreateAsync(
+        CreateProductRequest request, NpgsqlConnection db,
+        ClaimsPrincipal user, CancellationToken ct = default)
+    {
+        var userId = user.FindFirstValue(ClaimTypes.NameIdentifier);
+        var id = Guid.NewGuid();
+        await db.OpenAsync(ct);
+
+        await db.ExecuteAsync("""
+            INSERT INTO products (id, user_id, name, description, price, image_url)
+            VALUES (@Id, @UserId, @Name, @Description, @Price, @ImageUrl)
+            """,
+            new { Id = id, UserId = userId, request.Name, request.Description,
+                  request.Price, request.ImageUrl });
+
+        return Results.Created($"/api/products/{id}", new { id });
+    }
+
+    private static async Task<IResult> UpdateAsync(
+        Guid id, UpdateProductRequest request, NpgsqlConnection db,
+        ClaimsPrincipal user, CancellationToken ct = default)
+    {
+        var userId = user.FindFirstValue(ClaimTypes.NameIdentifier);
+        await db.OpenAsync(ct);
+
+        var rows = await db.ExecuteAsync("""
+            UPDATE products SET name = @Name, description = @Description,
+            price = @Price, image_url = @ImageUrl, updated_at = now()
+            WHERE id = @Id AND user_id = @UserId
+            """,
+            new { Id = id, UserId = userId, request.Name, request.Description,
+                  request.Price, request.ImageUrl });
+
+        return rows == 0 ? Results.NotFound() : Results.NoContent();
+    }
+
+    private static async Task<IResult> DeleteAsync(
+        Guid id, NpgsqlConnection db, ClaimsPrincipal user, CancellationToken ct = default)
+    {
+        var userId = user.FindFirstValue(ClaimTypes.NameIdentifier);
+        await db.OpenAsync(ct);
+
+        var rows = await db.ExecuteAsync(
+            "DELETE FROM products WHERE id = @Id AND user_id = @UserId",
+            new { Id = id, UserId = userId });
+
+        return rows == 0 ? Results.NotFound() : Results.NoContent();
+    }
+}
+
+public sealed record ProductDto(
+    Guid Id, string Name, string? Description, decimal Price,
+    string? ImageUrl, DateTime CreatedAt, DateTime? UpdatedAt);
+
+public sealed record CreateProductRequest(
+    string Name, string? Description, decimal Price, string? ImageUrl);
+
+public sealed record UpdateProductRequest(
+    string Name, string? Description, decimal Price, string? ImageUrl);
+```
+
+### lib/supabase/client.ts (Browser Client)
+
+```typescript
+import { createBrowserClient } from "@supabase/ssr";
+
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+  );
+}
+```
+
+### lib/supabase/server.ts (Server Client)
+
+```typescript
+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) {
+          try {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options)
+            );
+          } catch {
+            // Ignored in Server Components (read-only)
+          }
+        },
+      },
+    }
+  );
+}
+```
+
+### app/(auth)/login/page.tsx (Supabase Auth)
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { createClient } from "@/lib/supabase/client";
+import { useRouter } from "next/navigation";
+
+export default function LoginPage() {
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const router = useRouter();
+  const supabase = createClient();
+
+  async function handleLogin(e: React.FormEvent) {
+    e.preventDefault();
+    setLoading(true);
+    setError(null);
+
+    const { error } = await supabase.auth.signInWithPassword({
+      email,
+      password,
+    });
+
+    if (error) {
+      setError(error.message);
+      setLoading(false);
+      return;
+    }
+
+    router.push("/dashboard/products");
+    router.refresh();
+  }
+
+  async function handleOAuthLogin(provider: "google" | "github") {
+    await supabase.auth.signInWithOAuth({
+      provider,
+      options: {
+        redirectTo: `${window.location.origin}/auth/callback`,
+      },
+    });
+  }
+
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <form onSubmit={handleLogin} className="w-full max-w-sm space-y-4">
+        <h1 className="text-2xl font-bold">Sign In</h1>
+
+        {error && (
+          <div className="rounded bg-red-50 p-3 text-sm text-red-600">
+            {error}
+          </div>
+        )}
+
+        <input
+          type="email"
+          placeholder="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          className="w-full rounded border px-3 py-2"
+          required
+        />
+
+        <input
+          type="password"
+          placeholder="Password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          className="w-full rounded border px-3 py-2"
+          required
+        />
+
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full rounded bg-blue-600 py-2 text-white hover:bg-blue-700 disabled:opacity-50"
+        >
+          {loading ? "Signing in..." : "Sign In"}
+        </button>
+
+        <div className="relative my-4">
+          <div className="absolute inset-0 flex items-center">
+            <div className="w-full border-t" />
+          </div>
+          <div className="relative flex justify-center text-sm">
+            <span className="bg-white px-2 text-gray-500">Or continue with</span>
+          </div>
+        </div>
+
+        <div className="flex gap-2">
+          <button
+            type="button"
+            onClick={() => handleOAuthLogin("google")}
+            className="flex-1 rounded border py-2 hover:bg-gray-50"
+          >
+            Google
+          </button>
+          <button
+            type="button"
+            onClick={() => handleOAuthLogin("github")}
+            className="flex-1 rounded border py-2 hover:bg-gray-50"
+          >
+            GitHub
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}
+```
+
+### app/(dashboard)/products/page.tsx (Server Component Data Fetch)
+
+```tsx
+import { createClient } from "@/lib/supabase/server";
+import { redirect } from "next/navigation";
+
+const API_URL = process.env.API_URL || "http://localhost:5000";
+
+interface Product {
+  id: string;
+  name: string;
+  description: string | null;
+  price: number;
+  imageUrl: string | null;
+  createdAt: string;
+}
+
+interface ProductsResponse {
+  items: Product[];
+  total: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+}
+
+export default async function ProductsPage({
+  searchParams,
+}: {
+  searchParams: Promise<{ page?: string; search?: string }>;
+}) {
+  const supabase = await createClient();
+  const { data: { session } } = await supabase.auth.getSession();
+
+  if (!session) {
+    redirect("/login");
+  }
+
+  const params = await searchParams;
+  const page = Number(params.page) || 1;
+  const search = params.search || "";
+
+  const url = new URL(`${API_URL}/api/products`);
+  url.searchParams.set("page", String(page));
+  if (search) url.searchParams.set("search", search);
+
+  const response = await fetch(url.toString(), {
+    headers: {
+      Authorization: `Bearer ${session.access_token}`,
+    },
+    cache: "no-store",
+  });
+
+  if (!response.ok) {
+    throw new Error("Failed to fetch products");
+  }
+
+  const data: ProductsResponse = await response.json();
+
+  return (
+    <div className="p-6">
+      <div className="mb-6 flex items-center justify-between">
+        <h1 className="text-2xl font-bold">Products</h1>
+        <a
+          href="/dashboard/products/new"
+          className="rounded bg-blue-600 px-4 py-2 text-white hover:bg-blue-700"
+        >
+          Add Product
+        </a>
+      </div>
+
+      <div className="overflow-x-auto rounded border">
+        <table className="w-full text-left text-sm">
+          <thead className="border-b bg-gray-50">
+            <tr>
+              <th className="px-4 py-3">Name</th>
+              <th className="px-4 py-3">Price</th>
+              <th className="px-4 py-3">Created</th>
+              <th className="px-4 py-3">Actions</th>
+            </tr>
+          </thead>
+          <tbody>
+            {data.items.map((product) => (
+              <tr key={product.id} className="border-b hover:bg-gray-50">
+                <td className="px-4 py-3 font-medium">{product.name}</td>
+                <td className="px-4 py-3">
+                  ${product.price.toFixed(2)}
+                </td>
+                <td className="px-4 py-3">
+                  {new Date(product.createdAt).toLocaleDateString()}
+                </td>
+                <td className="px-4 py-3">
+                  <a
+                    href={`/dashboard/products/${product.id}`}
+                    className="text-blue-600 hover:underline"
+                  >
+                    Edit
+                  </a>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      {data.totalPages > 1 && (
+        <div className="mt-4 flex justify-center gap-2">
+          {Array.from({ length: data.totalPages }, (_, i) => i + 1).map((p) => (
+            <a
+              key={p}
+              href={`?page=${p}${search ? `&search=${search}` : ""}`}
+              className={`rounded px-3 py-1 ${
+                p === page
+                  ? "bg-blue-600 text-white"
+                  : "border hover:bg-gray-50"
+              }`}
+            >
+              {p}
+            </a>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### RLS Policy for Products Table
+
+```sql
+-- supabase/migrations/001_create_products.sql
+
+CREATE TABLE products (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+    name TEXT NOT NULL,
+    description TEXT,
+    price NUMERIC(10,2) NOT NULL DEFAULT 0,
+    image_url TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ
+);
+
+-- Enable RLS
+ALTER TABLE products ENABLE ROW LEVEL SECURITY;
+
+-- Users can only see their own products
+CREATE POLICY "Users can view own products"
+    ON products FOR SELECT
+    USING (auth.uid() = user_id);
+
+-- Users can only insert their own products
+CREATE POLICY "Users can insert own products"
+    ON products FOR INSERT
+    WITH CHECK (auth.uid() = user_id);
+
+-- Users can only update their own products
+CREATE POLICY "Users can update own products"
+    ON products FOR UPDATE
+    USING (auth.uid() = user_id)
+    WITH CHECK (auth.uid() = user_id);
+
+-- Users can only delete their own products
+CREATE POLICY "Users can delete own products"
+    ON products FOR DELETE
+    USING (auth.uid() = user_id);
+
+-- Index for performance
+CREATE INDEX idx_products_user_id ON products(user_id);
+CREATE INDEX idx_products_name ON products USING gin(name gin_trgm_ops);
+```
+
+### Docker Compose (Local Development)
+
+```yaml
+# docker-compose.yml
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile.api
+    ports:
+      - "5000:8080"
+    environment:
+      ASPNETCORE_ENVIRONMENT: Development
+      Supabase__Url: ${SUPABASE_URL}
+      Supabase__JwtSecret: ${SUPABASE_JWT_SECRET}
+      Supabase__DbConnectionString: ${SUPABASE_DB_CONNECTION_STRING}
+      Supabase__ServiceRoleKey: ${SUPABASE_SERVICE_ROLE_KEY}
+      Cors__AllowedOrigins: "http://localhost:3000"
+    depends_on:
+      - web
+
+  web:
+    build:
+      context: .
+      dockerfile: Dockerfile.web
+    ports:
+      - "3000:3000"
+    environment:
+      NEXT_PUBLIC_SUPABASE_URL: ${SUPABASE_URL}
+      NEXT_PUBLIC_SUPABASE_ANON_KEY: ${SUPABASE_ANON_KEY}
+      NEXT_PUBLIC_API_URL: http://localhost:5000
+      API_URL: http://api:8080
+```
+
+## Folder Structure
+
+```
+project/
+├── src/
+│   ├── api/                          # .NET Backend
+│   │   ├── Endpoints/
+│   │   │   └── ProductsEndpoints.cs
+│   │   ├── DTOs/
+│   │   │   └── ProductDtos.cs
+│   │   ├── Program.cs
+│   │   └── Api.csproj
+│   │
+│   └── web/                          # Next.js Frontend
+│       ├── app/
+│       │   ├── (auth)/
+│       │   │   ├── login/page.tsx
+│       │   │   └── signup/page.tsx
+│       │   ├── (dashboard)/
+│       │   │   └── products/
+│       │   │       ├── page.tsx
+│       │   │       ├── [id]/page.tsx
+│       │   │       └── new/page.tsx
+│       │   ├── auth/callback/route.ts
+│       │   ├── layout.tsx
+│       │   └── page.tsx
+│       ├── components/
+│       ├── lib/
+│       │   └── supabase/
+│       │       ├── client.ts
+│       │       └── server.ts
+│       └── types/
+│
+├── supabase/
+│   └── migrations/
+│       └── 001_create_products.sql
+│
+├── docker-compose.yml
+├── Dockerfile.api
+└── Dockerfile.web
+```
+
+## Quick Start
+
+```bash
+# 1. Create Supabase project at https://supabase.com
+# 2. Copy env vars
+cp .env.example .env
+# Fill in SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_JWT_SECRET, etc.
+
+# 3. Run migrations in Supabase SQL Editor (or via CLI)
+supabase db push
+
+# 4. Start local dev
+docker-compose up -d
+
+# API: http://localhost:5000
+# Web: http://localhost:3000
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*