@polymorphism-tech/morph-spec 3.0.1 → 3.2.0

package/stacks/nextjs-supabase/.morph/templates/contracts.ts

@@ -0,0 +1,168 @@
+// ============================================================
+// CONTRACTS: {{FEATURE_NAME_TITLE}}
+// Stack: Next.js + Supabase
+// Generated by MORPH Framework
+// Date: {{DATE}}
+// ============================================================
+
+// ----- Supabase Config -----
+
+export interface SupabaseConfig {
+  url: string;
+  anonKey: string;
+}
+
+// ----- API Client Types -----
+
+export interface ApiClientConfig {
+  baseUrl: string;
+  getAccessToken: () => Promise<string | null>;
+}
+
+export interface ApiError {
+  message: string;
+  code: string;
+  statusCode: number;
+  details?: Record<string, string[]>;
+}
+
+export type ApiResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: ApiError };
+
+// ----- Pagination -----
+
+export interface PaginationQuery {
+  page?: number;
+  pageSize?: number;
+}
+
+export interface PagedResult<T> {
+  items: T[];
+  totalCount: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrevious: boolean;
+}
+
+// ----- Supabase Client Type Aliases -----
+// Generated by: supabase gen types typescript --project-id <id> > types/database.ts
+
+export type Tables<T extends keyof Database["public"]["Tables"]> =
+  Database["public"]["Tables"][T]["Row"];
+
+export type Insertable<T extends keyof Database["public"]["Tables"]> =
+  Database["public"]["Tables"][T]["Insert"];
+
+export type Updatable<T extends keyof Database["public"]["Tables"]> =
+  Database["public"]["Tables"][T]["Update"];
+
+// ----- Database Schema (placeholder - replace with generated types) -----
+
+export interface Database {
+  public: {
+    Tables: {
+      {{FEATURE_NAME}}: {
+        Row: {
+          id: string;
+          name: string;
+          user_id: string;
+          status: {{FEATURE_NAME_PASCAL}}Status;
+          created_at: string;
+          updated_at: string | null;
+        };
+        Insert: {
+          id?: string;
+          name: string;
+          user_id?: string;
+          status?: {{FEATURE_NAME_PASCAL}}Status;
+          created_at?: string;
+          updated_at?: string | null;
+        };
+        Update: {
+          id?: string;
+          name?: string;
+          user_id?: string;
+          status?: {{FEATURE_NAME_PASCAL}}Status;
+          created_at?: string;
+          updated_at?: string | null;
+        };
+      };
+    };
+    Views: Record<string, never>;
+    Functions: Record<string, never>;
+    Enums: {
+      {{FEATURE_NAME}}_status: {{FEATURE_NAME_PASCAL}}Status;
+    };
+  };
+}
+
+// ----- Feature Types -----
+
+export type {{FEATURE_NAME_PASCAL}}Status =
+  | "draft"
+  | "active"
+  | "completed"
+  | "archived"
+  | "failed"
+  | "cancelled";
+
+export interface {{FEATURE_NAME_PASCAL}} {
+  id: string;
+  name: string;
+  userId: string;
+  status: {{FEATURE_NAME_PASCAL}}Status;
+  createdAt: string;
+  updatedAt: string | null;
+}
+
+export interface Create{{FEATURE_NAME_PASCAL}}Input {
+  name: string;
+  // Add other required fields
+}
+
+export interface Update{{FEATURE_NAME_PASCAL}}Input {
+  name?: string;
+  // Add other updatable fields
+}
+
+// ----- Storage Types -----
+
+export interface StorageUpload {
+  bucket: string;
+  path: string;
+  file: File;
+  contentType?: string;
+}
+
+export interface StorageFile {
+  id: string;
+  name: string;
+  bucket: string;
+  path: string;
+  publicUrl: string;
+  size: number;
+  contentType: string;
+  createdAt: string;
+}
+
+// ----- Auth Types -----
+
+export interface AuthUser {
+  id: string;
+  email: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+}
+
+export interface AuthSession {
+  user: AuthUser;
+  accessToken: string;
+  expiresAt: number;
+}
+
+// ----- Form Schemas (use with zod) -----
+// Define zod schemas in component files, not here.
+// This file is for type definitions only.

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

@@ -0,0 +1,115 @@
+# Architecture Decision Records - {{FEATURE_NAME_TITLE}}
+
+## ADR-001: {Decision Title}
+
+**Date:** {{DATE}}
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Deciders:** MORPH Agents, Developer
+
+### Context
+
+{Describe the context and problem that led to this decision}
+
+### Decision
+
+{Describe the decision made}
+
+### Consequences
+
+**Pros:**
+- {Positive consequence 1}
+- {Positive consequence 2}
+
+**Cons:**
+- {Negative consequence 1}
+
+**Risks:**
+- {Identified risk}
+
+### Alternatives Considered
+
+#### Option A: {Name}
+- Pros: {advantages}
+- Cons: {disadvantages}
+- **Rejected because:** {reason}
+
+#### Option B: {Name}
+- Pros: {advantages}
+- Cons: {disadvantages}
+- **Rejected because:** {reason}
+
+---
+
+## ADR-002: Database Access Strategy
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+### Context
+
+Need to decide how the .NET API accesses Supabase PostgreSQL.
+
+### Decision
+
+Use Dapper with Npgsql for direct SQL queries. No EF Core.
+
+### Consequences
+
+**Pros:**
+- Full control over SQL queries
+- Better performance (no ORM overhead)
+- Direct access to PostgreSQL features (jsonb, pgvector, functions)
+- RLS policies apply naturally through connection
+
+**Cons:**
+- No automatic migrations (use Supabase CLI instead)
+- Manual SQL query writing
+- No change tracking
+
+---
+
+## ADR-003: Auth Strategy
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+### Context
+
+Need authentication for both Next.js frontend and .NET API.
+
+### Decision
+
+Use Supabase Auth with @supabase/ssr on frontend. Validate JWT tokens in .NET API middleware.
+
+### Consequences
+
+**Pros:**
+- Single auth provider for both layers
+- RLS policies work automatically with auth.uid()
+- Built-in social login, magic links, email/password
+- No separate auth service to maintain
+
+**Cons:**
+- Coupled to Supabase ecosystem
+- JWT secret must be shared with .NET API
+
+---
+
+## Template for New ADRs
+
+```markdown
+## ADR-XXX: {Title}
+
+**Date:**
+**Status:** Proposed | Accepted | Deprecated | Superseded
+
+### Context
+{Why is this decision needed?}
+
+### Decision
+{What was decided?}
+
+### Consequences
+**Pros:** {list}
+**Cons:** {list}
+```

package/stacks/nextjs-supabase/.morph/templates/dockerfile-api.dockerfile

@@ -0,0 +1,38 @@
+# ============================================================
+# Dockerfile: .NET 10 API ({{FEATURE_NAME_TITLE}})
+# Stack: Next.js + Supabase + .NET API
+# Generated by MORPH Framework
+# ============================================================
+
+# Stage 1: Build
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+
+# Copy project file and restore dependencies
+COPY *.csproj .
+RUN dotnet restore
+
+# Copy source code and publish
+COPY . .
+RUN dotnet publish -c Release -o /app/publish --no-restore
+
+# Stage 2: Runtime
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
+WORKDIR /app
+
+# Copy published output
+COPY --from=build /app/publish .
+
+# Configuration
+ENV ASPNETCORE_URLS=http://+:8080
+ENV ASPNETCORE_ENVIRONMENT=Production
+
+# Expose port
+EXPOSE 8080
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:8080/health || exit 1
+
+# Entrypoint
+ENTRYPOINT ["dotnet", "Api.dll"]

package/stacks/nextjs-supabase/.morph/templates/dockerfile-web.dockerfile

@@ -0,0 +1,48 @@
+# ============================================================
+# Dockerfile: Next.js Frontend ({{FEATURE_NAME_TITLE}})
+# Stack: Next.js + Supabase
+# Generated by MORPH Framework
+# Requires: output: "standalone" in next.config.ts
+# ============================================================
+
+# Stage 1: Install dependencies
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+# Stage 2: Build application
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+# Stage 3: Production runtime
+FROM node:22-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+# Create non-root user
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 nextjs
+
+# Copy build output
+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
+
+# Switch to non-root user
+USER nextjs
+
+# Expose port
+EXPOSE 3000
+
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+# Start server
+CMD ["node", "server.js"]

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

@@ -0,0 +1,145 @@
+# Feature Proposal: {{FEATURE_NAME_TITLE}}
+
+> Proposal for a new feature. This document describes WHAT and WHY.
+> For technical details, see `spec.md`.
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Proposed** | {{DATE}} |
+| **Author** | {{AUTHOR}} |
+| **Status** | Draft / Under Review / Approved / Rejected |
+| **Priority** | High / Medium / Low |
+| **Stack** | Next.js + Supabase + .NET API |
+
+---
+
+## Overview
+
+{Brief 2-3 sentence summary of the feature}
+
+---
+
+## Problem Statement
+
+### What is the problem?
+
+{Describe the problem this feature solves. Be specific.}
+
+### Who is affected?
+
+{Who suffers from this problem? End users? Developers? Operations?}
+
+### What is the impact?
+
+{What is the impact of NOT solving this problem?}
+- User productivity loss: {X}
+- Revenue impact: {X}
+- User satisfaction: {X}
+
+---
+
+## Proposed Solution
+
+### Key Features
+
+1. **{Feature 1}** - {brief description}
+2. **{Feature 2}** - {brief description}
+3. **{Feature 3}** - {brief description}
+
+### Technical Approach
+
+| Layer | Technology | Role |
+|-------|-----------|------|
+| **Database** | Supabase (PostgreSQL + RLS) | {tables, policies, storage} |
+| **Backend API** | .NET 10 Minimal API | {endpoints, business logic} |
+| **Frontend** | Next.js 15 (App Router) | {pages, components, auth} |
+| **Infra** | EasyPanel + Docker | {deployment, SSL} |
+
+### User Journey
+
+```
+1. User {initial action}
+2. System {response}
+3. User {next action}
+4. System {final result}
+```
+
+---
+
+## Cost Estimate
+
+| Resource | Provider | Monthly Cost | Notes |
+|----------|----------|-------------|-------|
+| Supabase | Free / Pro | $0 - $25 | {DB, Auth, Storage, Realtime} |
+| VPS (EasyPanel) | {provider} | ${X} | {API + Web containers} |
+| External APIs | {provider} | ${X} | {if applicable} |
+| **Total** | | **${X}/month** | |
+
+---
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| {Risk 1} | High/Med/Low | High/Med/Low | {mitigation strategy} |
+| {Risk 2} | High/Med/Low | High/Med/Low | {mitigation strategy} |
+
+---
+
+## Scope
+
+### In Scope
+
+- {Item 1}
+- {Item 2}
+
+### Out of Scope
+
+- {Item 1}
+- {Item 2}
+
+---
+
+## Success Metrics
+
+| Metric | Current | Target |
+|--------|---------|--------|
+| {Metric 1} | {X} | {Y} |
+| {Metric 2} | {X} | {Y} |
+
+---
+
+## Dependencies
+
+- [ ] {Dependency 1} - {status}
+- [ ] {Dependency 2} - {status}
+
+---
+
+## Estimated Effort
+
+| Phase | Estimate |
+|-------|----------|
+| Design & Spec | {X}h |
+| Database & Migrations | {X}h |
+| Backend API | {X}h |
+| Frontend | {X}h |
+| Testing | {X}h |
+| **Total** | **{X}h** |
+
+---
+
+## Next Steps
+
+Once approved:
+1. Create detailed `spec.md` with technical design
+2. Define contracts (`contracts.cs` + `contracts.ts`)
+3. Record decisions in `decisions.md`
+4. Break down into `tasks.md`
+5. Begin implementation
+
+---
+
+*Created with MORPH Framework*

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

@@ -0,0 +1,134 @@
+# Feature Recap: {{FEATURE_NAME_TITLE}}
+
+## Summary
+
+| Field | Value |
+|-------|-------|
+| **Feature ID** | {{FEATURE_NAME}} |
+| **Completed** | {{DATE}} |
+| **Total Tasks** | {X} |
+| **Time Spent** | {X}h |
+| **Agents Used** | {list} |
+| **Stack** | Next.js + Supabase + .NET API |
+
+---
+
+## Tasks Completed
+
+| ID | Title | Category | Duration |
+|----|-------|----------|----------|
+| T001 | {title} | Database | {X}min |
+| T002 | {title} | Backend | {X}min |
+| T003 | {title} | Frontend | {X}min |
+
+---
+
+## Validation Results
+
+| Validator | Status | Details |
+|-----------|--------|---------|
+| contract-compliance | Pass/Fail | {details} |
+| architecture | Pass/Fail | {details} |
+| design-system | Pass/Fail | {details} |
+| coding-standards | Pass/Fail | {details} |
+
+---
+
+## What Was Delivered
+
+### Functionality
+- {Functionality 1 delivered}
+- {Functionality 2 delivered}
+- {Functionality 3 delivered}
+
+### Database (Supabase)
+- Tables: {list}
+- RLS Policies: {count} policies
+- Migrations: {count} files
+
+### Backend API (.NET)
+- Endpoints: {count} endpoints
+- Services: {list}
+
+### Frontend (Next.js)
+- Pages: {list}
+- Components: {list}
+
+---
+
+## Files Created
+
+```
+supabase/migrations/{files}
+backend/src/{files}
+frontend/src/{files}
+```
+
+## Files Modified
+
+```
+{list of modified files}
+```
+
+---
+
+## Architecture Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| {Decision 1} | {Reason} |
+| {Decision 2} | {Reason} |
+
+See full ADRs in `decisions.md`
+
+---
+
+## Test Coverage
+
+| Type | Files | Coverage |
+|------|-------|----------|
+| Backend Unit | {X} | {X}% |
+| Frontend Component | {X} | {X}% |
+
+---
+
+## Lessons Learned
+
+### What Went Well
+- {Positive point 1}
+- {Positive point 2}
+
+### What Could Be Improved
+- {Improvement point 1}
+- {Improvement point 2}
+
+### Recommendations for Future
+- {Recommendation 1}
+- {Recommendation 2}
+
+---
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Tasks Completed | {X}/{X} |
+| Checkpoints Passed | {X} |
+| Validation Passes | {X}/{X} |
+| Bugs Found | {X} |
+| Bugs Fixed | {X} |
+
+---
+
+## Related Resources
+
+- **Proposal:** `proposal.md`
+- **Spec:** `spec.md`
+- **Contracts (.NET):** `contracts.cs`
+- **Contracts (TS):** `contracts.ts`
+- **Tasks:** `tasks.md`
+- **Decisions:** `decisions.md`
+
+---
+
+*Generated by MORPH Framework on {{DATE}}*

package/stacks/nextjs-supabase/.morph/templates/rls-policy.sql

@@ -0,0 +1,57 @@
+-- ============================================================
+-- RLS Policy: {{FEATURE_NAME_TITLE}}
+-- Stack: Next.js + Supabase
+-- Generated by MORPH Framework
+-- Date: {{DATE}}
+-- ============================================================
+
+-- Enable RLS on table
+alter table public.{{TABLE_NAME}} enable row level security;
+
+-- Force RLS for table owner (prevents bypassing)
+alter table public.{{TABLE_NAME}} force row level security;
+
+-- Policy: {{POLICY_NAME}}
+-- Operation: {{OPERATION}} (SELECT | INSERT | UPDATE | DELETE | ALL)
+
+-- SELECT policy: users can read their own rows
+create policy "{{POLICY_NAME}}_select"
+  on public.{{TABLE_NAME}}
+  for select
+  using ({{USING_EXPRESSION}});
+
+-- INSERT policy: users can insert rows for themselves
+create policy "{{POLICY_NAME}}_insert"
+  on public.{{TABLE_NAME}}
+  for insert
+  with check ({{WITH_CHECK_EXPRESSION}});
+
+-- UPDATE policy: users can update their own rows
+create policy "{{POLICY_NAME}}_update"
+  on public.{{TABLE_NAME}}
+  for update
+  using ({{USING_EXPRESSION}})
+  with check ({{WITH_CHECK_EXPRESSION}});
+
+-- DELETE policy: users can delete their own rows
+create policy "{{POLICY_NAME}}_delete"
+  on public.{{TABLE_NAME}}
+  for delete
+  using ({{USING_EXPRESSION}});
+
+-- ============================================================
+-- Common USING / WITH CHECK expressions:
+--
+-- Owner-based:
+--   auth.uid() = user_id
+--
+-- Role-based:
+--   auth.jwt() ->> 'role' = 'admin'
+--
+-- Organization-based:
+--   org_id in (select org_id from public.org_members where user_id = auth.uid())
+--
+-- Public read, owner write:
+--   SELECT using (true)
+--   INSERT/UPDATE/DELETE using (auth.uid() = user_id)
+-- ============================================================