@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

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

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