@polymorphism-tech/morph-spec 8.28.0 → 8.31.0

package/framework/templates/feature/decisions.md

@@ -1,122 +1,122 @@
-# Architecture Decision Records - {{titleCase FEATURE_NAME}}
-
-## 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}
-
----
-
-{{#if (eq STACK "nextjs-neon")}}
-## ADR-002: Database Access Strategy
-
-**Date:** {{DATE}}
-**Status:** Accepted
-
-### Context
-
-Need to decide how the .NET API accesses Neon 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 Neon CLI / dotnet ef 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 Neon Auth (Better Auth) for authentication. Auth data lives in the Neon database. JWT validated by .NET API middleware.
-
-### Consequences
-
-**Pros:**
-- Auth data in same database — no external provider, no sync delays
-- RLS policies work with Neon Auth JWT via auth.user_id() / pg_session_jwt
-- Built-in social login, email/password via @neondatabase/auth SDK
-- Branch isolation — each Neon branch gets isolated auth data
-- No webhooks needed — query neon_auth schema directly
-
-**Cons:**
-- Neon Auth is currently in Beta
-- JWT must be forwarded to .NET API for backend auth
-{{/if}}
-
----
-
-## 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}
-```
-
----
-
-*Generated by MORPH Framework*
+# Architecture Decision Records - {{titleCase FEATURE_NAME}}
+
+## 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}
+
+---
+
+{{#if (eq STACK "nextjs-neon")}}
+## ADR-002: Database Access Strategy
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+### Context
+
+Need to decide how the .NET API accesses Neon 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 Neon CLI / dotnet ef 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 Neon Auth (Better Auth) for authentication. Auth data lives in the Neon database. JWT validated by .NET API middleware.
+
+### Consequences
+
+**Pros:**
+- Auth data in same database — no external provider, no sync delays
+- RLS policies work with Neon Auth JWT via auth.user_id() / pg_session_jwt
+- Built-in social login, email/password via @neondatabase/auth SDK
+- Branch isolation — each Neon branch gets isolated auth data
+- No webhooks needed — query neon_auth schema directly
+
+**Cons:**
+- Neon Auth is currently in Beta
+- JWT must be forwarded to .NET API for backend auth
+{{/if}}
+
+---
+
+## 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}
+```
+
+---
+
+*Generated by MORPH Framework*

package/framework/templates/frontend/nextjs/Dockerfile.nextjs.hbs

@@ -1,43 +1,43 @@
-# Multi-stage Next.js production build for Coolify
-# Stage 1: Dependencies
-FROM node:20-alpine AS deps
-RUN apk add --no-cache libc6-compat
-WORKDIR /app
-
-COPY package.json package-lock.json* ./
-RUN npm ci --only=production && npm cache clean --force
-
-# Stage 2: Build
-FROM node:20-alpine AS builder
-WORKDIR /app
-
-COPY --from=deps /app/node_modules ./node_modules
-COPY . .
-
-# Build args for NEXT_PUBLIC_ variables (must be available at build time)
-ARG NEXT_PUBLIC_APP_URL
-ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL
-
-RUN npm run build
-
-# Stage 3: Production runner
-FROM node:20-alpine AS runner
-WORKDIR /app
-
-ENV NODE_ENV=production
-ENV NEXT_TELEMETRY_DISABLED=1
-
-RUN addgroup --system --gid 1001 nodejs
-RUN adduser --system --uid 1001 nextjs
-
-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
-
-USER nextjs
-
-EXPOSE 3000
-ENV PORT=3000
-ENV HOSTNAME="0.0.0.0"
-
-CMD ["node", "server.js"]
+# Multi-stage Next.js production build for Coolify
+# Stage 1: Dependencies
+FROM node:20-alpine AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm ci --only=production && npm cache clean --force
+
+# Stage 2: Build
+FROM node:20-alpine AS builder
+WORKDIR /app
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Build args for NEXT_PUBLIC_ variables (must be available at build time)
+ARG NEXT_PUBLIC_APP_URL
+ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL
+
+RUN npm run build
+
+# Stage 3: Production runner
+FROM node:20-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+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
+
+USER nextjs
+
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "server.js"]

package/framework/templates/frontend/nextjs/client-component.tsx.hbs

@@ -1,26 +1,26 @@
-// features/{{kebabCase featureName}}/components/{{kebabCase featureName}}-list.tsx
-'use client';
-
-import { use{{pascalCase featureName}}s } from '@/features/{{kebabCase featureName}}/hooks/use-{{kebabCase featureName}}s';
-import { DataTable } from '@/components/data-table';
-import type { {{pascalCase featureName}} } from '@/features/{{kebabCase featureName}}/types/{{kebabCase featureName}}.types';
-import type { ColumnDef } from '@tanstack/react-table';
-
-const columns: ColumnDef<{{pascalCase featureName}}>[] = [
-  { accessorKey: 'id', header: 'ID' },
-  { accessorKey: 'name', header: 'Name' },
-];
-
-interface {{pascalCase featureName}}ListProps {
-  initialData?: {{pascalCase featureName}}[];
-}
-
-export function {{pascalCase featureName}}List({ initialData }: {{pascalCase featureName}}ListProps) {
-  const { data = initialData ?? [], isLoading } = use{{pascalCase featureName}}s();
-
-  if (isLoading) {
-    return <div className="flex items-center justify-center h-32">Loading...</div>;
-  }
-
-  return <DataTable columns={columns} data={data} />;
-}
+// features/{{kebabCase featureName}}/components/{{kebabCase featureName}}-list.tsx
+'use client';
+
+import { use{{pascalCase featureName}}s } from '@/features/{{kebabCase featureName}}/hooks/use-{{kebabCase featureName}}s';
+import { DataTable } from '@/components/data-table';
+import type { {{pascalCase featureName}} } from '@/features/{{kebabCase featureName}}/types/{{kebabCase featureName}}.types';
+import type { ColumnDef } from '@tanstack/react-table';
+
+const columns: ColumnDef<{{pascalCase featureName}}>[] = [
+  { accessorKey: 'id', header: 'ID' },
+  { accessorKey: 'name', header: 'Name' },
+];
+
+interface {{pascalCase featureName}}ListProps {
+  initialData?: {{pascalCase featureName}}[];
+}
+
+export function {{pascalCase featureName}}List({ initialData }: {{pascalCase featureName}}ListProps) {
+  const { data = initialData ?? [], isLoading } = use{{pascalCase featureName}}s();
+
+  if (isLoading) {
+    return <div className="flex items-center justify-center h-32">Loading...</div>;
+  }
+
+  return <DataTable columns={columns} data={data} />;
+}

package/framework/templates/frontend/nextjs/env.mjs.hbs

@@ -1,32 +1,32 @@
-// env.mjs — Zod-validated environment variables
-// Crashes at startup if required vars are missing — no silent undefined
-import { z } from 'zod';
-
-const serverSchema = z.object({
-  API_URL: z.string().url('API_URL must be a valid URL'),
-  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
-});
-
-const clientSchema = z.object({
-  NEXT_PUBLIC_APP_URL: z.string().url().optional(),
-});
-
-// Validate server-side env (only available on server)
-const serverEnv = serverSchema.safeParse(process.env);
-if (!serverEnv.success) {
-  console.error('❌ Invalid server environment variables:');
-  console.error(serverEnv.error.flatten().fieldErrors);
-  throw new Error('Invalid environment variables');
-}
-
-// Validate client-side env
-const clientEnv = clientSchema.safeParse({
-  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
-});
-if (!clientEnv.success) {
-  console.error('❌ Invalid client environment variables:');
-  console.error(clientEnv.error.flatten().fieldErrors);
-  throw new Error('Invalid client environment variables');
-}
-
-export const env = { ...serverEnv.data, ...clientEnv.data };
+// env.mjs — Zod-validated environment variables
+// Crashes at startup if required vars are missing — no silent undefined
+import { z } from 'zod';
+
+const serverSchema = z.object({
+  API_URL: z.string().url('API_URL must be a valid URL'),
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+});
+
+const clientSchema = z.object({
+  NEXT_PUBLIC_APP_URL: z.string().url().optional(),
+});
+
+// Validate server-side env (only available on server)
+const serverEnv = serverSchema.safeParse(process.env);
+if (!serverEnv.success) {
+  console.error('❌ Invalid server environment variables:');
+  console.error(serverEnv.error.flatten().fieldErrors);
+  throw new Error('Invalid environment variables');
+}
+
+// Validate client-side env
+const clientEnv = clientSchema.safeParse({
+  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+});
+if (!clientEnv.success) {
+  console.error('❌ Invalid client environment variables:');
+  console.error(clientEnv.error.flatten().fieldErrors);
+  throw new Error('Invalid client environment variables');
+}
+
+export const env = { ...serverEnv.data, ...clientEnv.data };

package/framework/templates/frontend/nextjs/feature-form.tsx.hbs

@@ -1,56 +1,56 @@
-// features/{{kebabCase featureName}}/components/create-{{kebabCase featureName}}-form.tsx
-'use client';
-
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
-import { Input } from '@/components/ui/input';
-import { Button } from '@/components/ui/button';
-import { useCreate{{pascalCase featureName}} } from '@/features/{{kebabCase featureName}}/hooks/use-create-{{kebabCase featureName}}';
-import { create{{pascalCase featureName}}Schema, type Create{{pascalCase featureName}}Input } from '@/features/{{kebabCase featureName}}/types/{{kebabCase featureName}}.schemas';
-
-interface Create{{pascalCase featureName}}FormProps {
-  onSuccess?: () => void;
-}
-
-export function Create{{pascalCase featureName}}Form({ onSuccess }: Create{{pascalCase featureName}}FormProps) {
-  const form = useForm<Create{{pascalCase featureName}}Input>({
-    resolver: zodResolver(create{{pascalCase featureName}}Schema),
-    defaultValues: { name: '' },
-  });
-
-  const { mutate: create{{pascalCase featureName}}, isPending } = useCreate{{pascalCase featureName}}();
-
-  function onSubmit(values: Create{{pascalCase featureName}}Input) {
-    create{{pascalCase featureName}}(values, {
-      onSuccess: () => { form.reset(); onSuccess?.(); },
-      onError: (error) => { form.setError('root', { message: error.message }); },
-    });
-  }
-
-  return (
-    <Form {...form}>
-      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
-        <FormField
-          control={form.control}
-          name="name"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Name</FormLabel>
-              <FormControl>
-                <Input placeholder="Enter name" {...field} />
-              </FormControl>
-              <FormMessage />
-            </FormItem>
-          )}
-        />
-        {form.formState.errors.root && (
-          <p className="text-sm text-destructive">{form.formState.errors.root.message}</p>
-        )}
-        <Button type="submit" disabled={isPending}>
-          {isPending ? 'Creating...' : 'Create {{pascalCase featureName}}'}
-        </Button>
-      </form>
-    </Form>
-  );
-}
+// features/{{kebabCase featureName}}/components/create-{{kebabCase featureName}}-form.tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
+import { Input } from '@/components/ui/input';
+import { Button } from '@/components/ui/button';
+import { useCreate{{pascalCase featureName}} } from '@/features/{{kebabCase featureName}}/hooks/use-create-{{kebabCase featureName}}';
+import { create{{pascalCase featureName}}Schema, type Create{{pascalCase featureName}}Input } from '@/features/{{kebabCase featureName}}/types/{{kebabCase featureName}}.schemas';
+
+interface Create{{pascalCase featureName}}FormProps {
+  onSuccess?: () => void;
+}
+
+export function Create{{pascalCase featureName}}Form({ onSuccess }: Create{{pascalCase featureName}}FormProps) {
+  const form = useForm<Create{{pascalCase featureName}}Input>({
+    resolver: zodResolver(create{{pascalCase featureName}}Schema),
+    defaultValues: { name: '' },
+  });
+
+  const { mutate: create{{pascalCase featureName}}, isPending } = useCreate{{pascalCase featureName}}();
+
+  function onSubmit(values: Create{{pascalCase featureName}}Input) {
+    create{{pascalCase featureName}}(values, {
+      onSuccess: () => { form.reset(); onSuccess?.(); },
+      onError: (error) => { form.setError('root', { message: error.message }); },
+    });
+  }
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Name</FormLabel>
+              <FormControl>
+                <Input placeholder="Enter name" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        {form.formState.errors.root && (
+          <p className="text-sm text-destructive">{form.formState.errors.root.message}</p>
+        )}
+        <Button type="submit" disabled={isPending}>
+          {isPending ? 'Creating...' : 'Create {{pascalCase featureName}}'}
+        </Button>
+      </form>
+    </Form>
+  );
+}

package/framework/templates/frontend/nextjs/page.tsx.hbs

@@ -1,22 +1,22 @@
-// app/(dashboard)/{{kebabCase featureName}}/page.tsx
-// Server Component — fetches initial data, renders feature component
-import { {{pascalCase featureName}}List } from '@/features/{{kebabCase featureName}}';
-
-async function get{{pascalCase featureName}}List() {
-  const res = await fetch(`${process.env.API_URL}/api/{{kebabCase featureName}}`, {
-    next: { revalidate: 30 },
-    headers: { 'Content-Type': 'application/json' },
-  });
-  if (!res.ok) throw new Error('Failed to fetch {{featureName}}');
-  return res.json();
-}
-
-export default async function {{pascalCase featureName}}Page() {
-  const data = await get{{pascalCase featureName}}List();
-  return (
-    <div className="container py-6">
-      <h1 className="text-2xl font-bold mb-6">{{pascalCase featureName}}</h1>
-      <{{pascalCase featureName}}List initialData={data} />
-    </div>
-  );
-}
+// app/(dashboard)/{{kebabCase featureName}}/page.tsx
+// Server Component — fetches initial data, renders feature component
+import { {{pascalCase featureName}}List } from '@/features/{{kebabCase featureName}}';
+
+async function get{{pascalCase featureName}}List() {
+  const res = await fetch(`${process.env.API_URL}/api/{{kebabCase featureName}}`, {
+    next: { revalidate: 30 },
+    headers: { 'Content-Type': 'application/json' },
+  });
+  if (!res.ok) throw new Error('Failed to fetch {{featureName}}');
+  return res.json();
+}
+
+export default async function {{pascalCase featureName}}Page() {
+  const data = await get{{pascalCase featureName}}List();
+  return (
+    <div className="container py-6">
+      <h1 className="text-2xl font-bold mb-6">{{pascalCase featureName}}</h1>
+      <{{pascalCase featureName}}List initialData={data} />
+    </div>
+  );
+}

package/framework/templates/frontend/nextjs/tsconfig.json.hbs

@@ -1,26 +1,26 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "lib": ["dom", "dom.iterable", "esnext"],
-    "allowJs": false,
-    "skipLibCheck": true,
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-    "forceConsistentCasingInFileNames": true,
-    "noEmit": true,
-    "esModuleInterop": true,
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "jsx": "preserve",
-    "incremental": true,
-    "plugins": [{ "name": "next" }],
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  },
-  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-  "exclude": ["node_modules"]
-}
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}