@polymorphism-tech/morph-spec 3.0.1 → 3.1.0

package/stacks/nextjs-supabase/.morph/templates/spec.md

@@ -0,0 +1,231 @@
+# Feature Specification: {{FEATURE_NAME_TITLE}}
+
+| Field | Value |
+|-------|-------|
+| **ID** | {{FEATURE_NAME}} |
+| **Status** | Draft / In Review / Approved / In Progress / Done |
+| **Created** | {{DATE}} |
+| **Stack** | Next.js + Supabase + .NET API |
+| **Complexity** | Low / Medium / High |
+| **Estimated Cost** | $X/month |
+| **Agents** | Core: All / Specialists: {list} |
+
+---
+
+## Overview
+
+**Problem:** {What problem this feature solves}
+
+**Solution:** {High-level solution}
+
+**Success Criteria:**
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+
+---
+
+## Requirements
+
+### Functional Requirements
+
+| ID | Description | Priority |
+|----|-------------|----------|
+| FR1 | {requirement} | Must |
+| FR2 | {requirement} | Must |
+| FR3 | {requirement} | Should |
+
+### Non-Functional Requirements
+
+| ID | Category | Target |
+|----|----------|--------|
+| NFR1 | Performance | {e.g., API response < 200ms p95} |
+| NFR2 | Reliability | {e.g., 99.9% uptime} |
+| NFR3 | Security | {e.g., All data access via RLS} |
+
+---
+
+## Technical Architecture
+
+### Stack
+
+| Component | Technology | Purpose |
+|-----------|-----------|---------|
+| Database | Supabase PostgreSQL | Data storage, RLS, Auth |
+| Storage | Supabase Storage | File uploads |
+| Realtime | Supabase Realtime | Live updates |
+| Backend API | .NET 10 Minimal API | Business logic, integrations |
+| Frontend | Next.js 15 (App Router) | SSR, UI, client interactions |
+| Auth | Supabase Auth (@supabase/ssr) | Authentication, JWT |
+| UI | shadcn/ui + Tailwind CSS | Components, styling |
+| Deployment | EasyPanel + Docker | Hosting, SSL |
+
+### Architecture Diagram
+
+```
+[Browser] --HTTPS--> [Next.js (SSR)]
+                         |
+                    [Supabase Client] --RLS--> [Supabase PostgreSQL]
+                         |                          |
+                    [.NET API] ---service_role----> [Supabase]
+                         |
+                    [External Services]
+```
+
+---
+
+## Data Model (Supabase)
+
+### {TableName}
+
+| Column | Type | Constraints | Default |
+|--------|------|-------------|---------|
+| id | uuid | PK | gen_random_uuid() |
+| user_id | uuid | FK -> auth.users(id), NOT NULL | |
+| {column} | {type} | {constraints} | {default} |
+| created_at | timestamptz | NOT NULL | now() |
+| updated_at | timestamptz | | |
+
+### RLS Policies
+
+| Table | Policy | Operation | Rule |
+|-------|--------|-----------|------|
+| {table} | Users read own | SELECT | auth.uid() = user_id |
+| {table} | Users insert own | INSERT | auth.uid() = user_id |
+| {table} | Users update own | UPDATE | auth.uid() = user_id |
+
+### Indexes
+
+| Table | Columns | Type | Purpose |
+|-------|---------|------|---------|
+| {table} | user_id | btree | Filter by owner |
+| {table} | created_at | btree | Sort by date |
+
+---
+
+## API Design (.NET Minimal API)
+
+### Endpoints
+
+| Method | Path | Description | Auth |
+|--------|------|-------------|------|
+| GET | /api/{{FEATURE_NAME}}/{id} | Get by ID | Required |
+| GET | /api/{{FEATURE_NAME}} | List (paginated) | Required |
+| POST | /api/{{FEATURE_NAME}} | Create | Required |
+| PUT | /api/{{FEATURE_NAME}}/{id} | Update | Required |
+| DELETE | /api/{{FEATURE_NAME}}/{id} | Delete | Required |
+
+### Request/Response Examples
+
+```json
+// POST /api/{{FEATURE_NAME}}
+// Request
+{
+  "name": "Example",
+  "description": "Example description"
+}
+
+// Response 201
+{
+  "id": "uuid",
+  "name": "Example",
+  "description": "Example description",
+  "createdAt": "2026-01-01T00:00:00Z"
+}
+```
+
+---
+
+## Frontend Design (Next.js)
+
+### Pages
+
+| Route | Type | Description |
+|-------|------|-------------|
+| /{{FEATURE_NAME}} | Server | List page with SSR |
+| /{{FEATURE_NAME}}/[id] | Server | Detail page |
+| /{{FEATURE_NAME}}/new | Client | Create form |
+
+### Components
+
+| Component | Type | Props |
+|-----------|------|-------|
+| {{FEATURE_NAME_PASCAL}}List | Client | initialData, pagination |
+| {{FEATURE_NAME_PASCAL}}Form | Client | onSuccess, defaultValues? |
+| {{FEATURE_NAME_PASCAL}}Card | Server | item |
+
+### State Management
+
+| State | Location | Strategy |
+|-------|----------|----------|
+| Server data | React Query | Cache + invalidation |
+| Form state | react-hook-form | Local |
+| Auth state | Supabase client | Cookie-based session |
+| Realtime | Supabase channel | Invalidate query on change |
+
+---
+
+## Infrastructure (EasyPanel)
+
+### Services
+
+| Service | Image | Port | Resources |
+|---------|-------|------|-----------|
+| api | Custom (.NET) | 8080 | 256MB / 0.25 CPU |
+| web | Custom (Next.js) | 3000 | 256MB / 0.25 CPU |
+
+### Environment Variables
+
+| Variable | Service | Source |
+|----------|---------|--------|
+| SUPABASE_URL | api, web | EasyPanel secrets |
+| SUPABASE_ANON_KEY | web | EasyPanel secrets |
+| SUPABASE_SERVICE_KEY | api | EasyPanel secrets |
+| SUPABASE_JWT_SECRET | api | EasyPanel secrets |
+
+---
+
+## Packages
+
+### Backend (.NET)
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| Npgsql | latest | PostgreSQL driver |
+| Dapper | latest | Micro-ORM |
+| Microsoft.AspNetCore.Authentication.JwtBearer | 10.0.x | JWT auth |
+
+### Frontend (npm)
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| @supabase/ssr | latest | Supabase SSR client |
+| @tanstack/react-query | ^5 | Data fetching |
+| react-hook-form | ^7 | Form management |
+| zod | ^3 | Validation |
+| @hookform/resolvers | latest | Zod integration |
+
+---
+
+## Security
+
+| Action | Required Policy |
+|--------|-----------------|
+| View | RLS: auth.uid() = user_id |
+| Create | RLS: auth.uid() = user_id |
+| Update | RLS: auth.uid() = user_id |
+| Delete | RLS: auth.uid() = user_id |
+| Admin | .NET API with service_role key |
+
+---
+
+## Definition of Done
+
+- [ ] Database migrations applied
+- [ ] RLS policies tested
+- [ ] API endpoints implemented and tested
+- [ ] Frontend pages and components built
+- [ ] Auth flow working (login, signup, protected routes)
+- [ ] Tests > 80% coverage
+- [ ] Docker images building successfully
+- [ ] Deploy to EasyPanel verified
+- [ ] Recap.md generated

package/stacks/nextjs-supabase/.morph/templates/supabase-migration.sql

@@ -0,0 +1,100 @@
+-- ============================================================
+-- Migration: {{FEATURE_NAME_TITLE}}
+-- Stack: Next.js + Supabase
+-- Generated by MORPH Framework
+-- Date: {{DATE}}
+-- Run: supabase db push
+-- ============================================================
+
+-- ============================================================
+-- 1. TABLE CREATION
+-- ============================================================
+
+create table if not exists public.{{TABLE_NAME}} (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users(id) on delete cascade,
+  name text not null,
+  status text not null default 'draft'
+    check (status in ('draft', 'active', 'completed', 'archived', 'failed', 'cancelled')),
+  -- Add feature-specific columns here
+  metadata jsonb default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz
+);
+
+-- Comment on table
+comment on table public.{{TABLE_NAME}} is '{{FEATURE_NAME_TITLE}} - managed by MORPH Framework';
+
+-- ============================================================
+-- 2. INDEXES
+-- ============================================================
+
+-- Index for filtering by owner
+create index if not exists idx_{{TABLE_NAME}}_user_id
+  on public.{{TABLE_NAME}} (user_id);
+
+-- Index for filtering by status
+create index if not exists idx_{{TABLE_NAME}}_status
+  on public.{{TABLE_NAME}} (status);
+
+-- Index for sorting by creation date
+create index if not exists idx_{{TABLE_NAME}}_created_at
+  on public.{{TABLE_NAME}} (created_at desc);
+
+-- ============================================================
+-- 3. UPDATED_AT TRIGGER
+-- ============================================================
+
+-- Function to auto-update updated_at
+create or replace function public.update_updated_at_column()
+returns trigger as $$
+begin
+  new.updated_at = now();
+  return new;
+end;
+$$ language plpgsql;
+
+-- Trigger for auto-updating updated_at
+create trigger set_{{TABLE_NAME}}_updated_at
+  before update on public.{{TABLE_NAME}}
+  for each row execute function public.update_updated_at_column();
+
+-- ============================================================
+-- 4. ROW LEVEL SECURITY
+-- ============================================================
+
+-- Enable RLS
+alter table public.{{TABLE_NAME}} enable row level security;
+
+-- Users can read their own rows
+create policy "Users can read own {{TABLE_NAME}}"
+  on public.{{TABLE_NAME}}
+  for select
+  using (auth.uid() = user_id);
+
+-- Users can insert rows for themselves
+create policy "Users can insert own {{TABLE_NAME}}"
+  on public.{{TABLE_NAME}}
+  for insert
+  with check (auth.uid() = user_id);
+
+-- Users can update their own rows
+create policy "Users can update own {{TABLE_NAME}}"
+  on public.{{TABLE_NAME}}
+  for update
+  using (auth.uid() = user_id)
+  with check (auth.uid() = user_id);
+
+-- Users can delete their own rows
+create policy "Users can delete own {{TABLE_NAME}}"
+  on public.{{TABLE_NAME}}
+  for delete
+  using (auth.uid() = user_id);
+
+-- ============================================================
+-- 5. GRANTS
+-- ============================================================
+
+-- Grant access to authenticated users (via Supabase API)
+grant select, insert, update, delete on public.{{TABLE_NAME}} to authenticated;
+grant usage on schema public to authenticated;

package/stacks/nextjs-supabase/.morph/templates/tasks.md

@@ -0,0 +1,257 @@
+# Tasks - {{FEATURE_NAME_TITLE}}
+
+> Implementation checklist for the feature.
+> Update status as you progress.
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| **Total Tasks** | 0 |
+| **Completed** | 0 |
+| **In Progress** | 0 |
+| **Pending** | 0 |
+| **Estimated** | 0h |
+| **Actual** | 0h |
+
+---
+
+## Task Granularity
+
+### Ideal Task
+- 15-60 minutes of implementation
+- 1-5 files modified
+- Testable in isolation
+- Independent commit possible
+
+### Signs of Too Broad (Split)
+**Bad example:** "Implement document upload"
+**Split into:**
+- T001: Create Supabase migration for documents table + RLS
+- T002: Create .NET DTOs and service interface
+- T003: Implement Dapper repository
+- T004: Create API endpoints
+- T005: Build Next.js upload form component
+
+### Signs of Too Granular (Merge)
+**Bad example:** "Create title field", "Create content field"
+**Merge into:** "Create documents table with all columns"
+
+---
+
+## Checkpoints
+
+| After | Type | Description | Status |
+|-------|------|-------------|--------|
+| T003 | Review | Review database schema and RLS policies | Pending |
+| T006 | Review | Review API implementation | Pending |
+| T009 | Approval | Approve UI before testing | Pending |
+
+---
+
+## Phase 1: Database & Migrations
+
+### T001: Create Supabase migration
+- **Type:** Database
+- **Priority:** 1
+- **Estimate:** 30min
+- **Status:** [ ] Pending
+
+**Description:**
+Create migration with table definition, indexes, RLS policies.
+
+**Files:**
+- [ ] Create: `supabase/migrations/{timestamp}_create_{feature}_table.sql`
+
+---
+
+### T002: Create RLS policies
+- **Type:** Security
+- **Priority:** 1
+- **Estimate:** 20min
+- **Status:** [ ] Pending
+- **Dependencies:** T001
+
+**Description:**
+Define row-level security policies for all CRUD operations.
+
+**Files:**
+- [ ] Modify: `supabase/migrations/{timestamp}_create_{feature}_table.sql`
+
+---
+
+### T003: Generate TypeScript types
+- **Type:** Contract
+- **Priority:** 1
+- **Estimate:** 15min
+- **Status:** [ ] Pending
+- **Dependencies:** T001
+- **Checkpoint:** Review after this task
+
+**Description:**
+Run `supabase gen types typescript` and update Database type.
+
+**Files:**
+- [ ] Modify: `frontend/src/types/database.ts`
+
+---
+
+## Phase 2: Backend API (.NET)
+
+### T004: Define contracts (interfaces + DTOs)
+- **Type:** Contract
+- **Priority:** 1
+- **Estimate:** 30min
+- **Status:** [ ] Pending
+
+**Description:**
+Create service interface with all required methods. DTOs as records.
+
+**Files:**
+- [ ] Create: `backend/src/Application/Features/{Feature}/I{Feature}Service.cs`
+- [ ] Create: `backend/src/Application/Features/{Feature}/{Feature}Dtos.cs`
+
+---
+
+### T005: Implement Dapper repository
+- **Type:** Infrastructure
+- **Priority:** 2
+- **Estimate:** 45min
+- **Status:** [ ] Pending
+- **Dependencies:** T001, T004
+
+**Description:**
+Implement data access with Dapper + NpgsqlDataSource.
+
+**Files:**
+- [ ] Create: `backend/src/Infrastructure/Repositories/{Feature}Repository.cs`
+
+---
+
+### T006: Create Minimal API endpoints
+- **Type:** API
+- **Priority:** 2
+- **Estimate:** 45min
+- **Status:** [ ] Pending
+- **Dependencies:** T004, T005
+- **Checkpoint:** Review after this task
+
+**Description:**
+Map endpoints with auth, validation, and proper HTTP status codes.
+
+**Files:**
+- [ ] Create: `backend/src/Api/Endpoints/{Feature}Endpoints.cs`
+- [ ] Modify: `backend/src/Api/Program.cs`
+
+---
+
+## Phase 3: Frontend (Next.js)
+
+### T007: Create React Query hooks
+- **Type:** Frontend
+- **Priority:** 2
+- **Estimate:** 30min
+- **Status:** [ ] Pending
+- **Dependencies:** T003
+
+**Description:**
+Create hooks for data fetching with Supabase client or API.
+
+**Files:**
+- [ ] Create: `frontend/src/hooks/use-{feature}.ts`
+
+---
+
+### T008: Create list page (Server Component)
+- **Type:** UI
+- **Priority:** 2
+- **Estimate:** 45min
+- **Status:** [ ] Pending
+- **Dependencies:** T007
+
+**Description:**
+Server-rendered list page with initial data fetch.
+
+**Files:**
+- [ ] Create: `frontend/src/app/{feature}/page.tsx`
+- [ ] Create: `frontend/src/components/{feature}/{feature}-list.tsx`
+
+---
+
+### T009: Create form component (Client Component)
+- **Type:** UI
+- **Priority:** 2
+- **Estimate:** 1h
+- **Status:** [ ] Pending
+- **Dependencies:** T007
+- **Checkpoint:** Approval after this task
+
+**Description:**
+Form with react-hook-form + zod validation.
+
+**Files:**
+- [ ] Create: `frontend/src/app/{feature}/new/page.tsx`
+- [ ] Create: `frontend/src/components/{feature}/{feature}-form.tsx`
+
+---
+
+## Phase 4: Testing
+
+### T010: Write backend unit tests
+- **Type:** Test
+- **Priority:** 2
+- **Estimate:** 1h
+- **Status:** [ ] Pending
+- **Dependencies:** T006
+
+**Description:**
+Unit tests for service layer and endpoints.
+
+**Files:**
+- [ ] Create: `backend/tests/Unit/{Feature}ServiceTests.cs`
+
+---
+
+### T011: Write frontend tests
+- **Type:** Test
+- **Priority:** 3
+- **Estimate:** 45min
+- **Status:** [ ] Pending
+- **Dependencies:** T009
+
+**Description:**
+Component tests with testing-library.
+
+**Files:**
+- [ ] Create: `frontend/src/components/{feature}/__tests__/{feature}-form.test.tsx`
+
+---
+
+## Phase 5: Deployment
+
+### T012: Create Dockerfiles
+- **Type:** Infra
+- **Priority:** 2
+- **Estimate:** 30min
+- **Status:** [ ] Pending
+- **Dependencies:** T006, T009
+
+**Description:**
+Multi-stage Dockerfiles for API and Web.
+
+**Files:**
+- [ ] Create: `backend/Dockerfile`
+- [ ] Create: `frontend/Dockerfile`
+
+---
+
+## Status Legend
+
+- [ ] Pending
+- [~] In Progress
+- [x] Completed
+- [!] Blocked
+
+---
+
+*Generated by MORPH Framework*