@polymorphism-tech/morph-spec 9.4.0 → 9.6.0

package/framework/standards/frontend/nextjs/data-fetching.md

@@ -9,16 +9,16 @@
 
 ---
 
-Server Components for initial page load. TanStack Query for client mutations and interactive data. Never `useEffect` for fetching.
+Server Components for initial page load. TanStack Query for client mutations and interactive data.
 
 ## Core Rules
 
 - ALWAYS use Server Components for initial data that doesn't require interactivity
 - ALWAYS use TanStack Query (`useQuery`, `useMutation`) for client-side data needs
-- NEVER use `useEffect(() => { fetch(...) }, [])` — this is the old pattern
 - ALWAYS validate API responses with Zod before using them
 - ALWAYS use query key factories for consistent cache invalidation
 - NEVER fetch a whole collection to page, sort or filter it in the browser — a list is paged on the server, with the query in the URL (`admin-app/data-table.md`)
+- Fetch inside `useEffect` and a DB driver in Next are lint errors (`frontend-nextjs-lint`)
 
 ## TanStack Query Setup
 
@@ -134,7 +134,6 @@ export function UserListClient({ initialData }: { initialData: User[] }) {
 
 | Wrong | Right | Why |
 |-------|-------|-----|
-| `useEffect(() => { fetch(...) }, [])` | `useQuery(...)` | Two renders, no cache, no SSR |
 | No Zod on API response | `schema.parse(await res.json())` | Type safety at runtime |
 | Hardcoded query keys: `['users']` | Key factory: `userKeys.lists()` | Consistent invalidation |
 | `queryClient.invalidateQueries(['users'])` | `{ queryKey: userKeys.lists() }` | Object syntax required in v5 |

package/framework/standards/frontend/nextjs/lint.md

@@ -0,0 +1,141 @@
+# ESLint Next.js — o lint cobra, a prosa não repete
+
+> **Scope:** nextjs
+> **Layer:** 0 (resumo injetado pela rule `nextjs-standards` (`**/*.ts`, `**/*.tsx`); o `stack-scan` acusa o projeto sem este arquivo)
+> **Keywords:** eslint, lint, eslint.config.mjs, no-restricted-imports, no-restricted-paths, no-restricted-syntax, no-default-export, no-explicit-any, framer-motion, zustand
+> **Load When:** projeto Next.js sem `eslint.config.mjs` com `no-restricted-imports`, ou o lint acusou uma destas regras
+
+**Verified against:** eslint 9.39.5, eslint-config-next 16.4.2 (typescript-eslint 8.71.2, eslint-plugin-import 2.32.0), next 16.4.2, typescript 6.0.3 (sonda: um arquivo ruim por regra → erro da regra esperada, `no-console` → aviso, arquivos conformes e o scaffold `morph-spec scaffold nextjs` → 0 problemas). Last-verified: 2026-10-18.
+
+---
+
+Regra de código que tem motivo e que uma máquina enxerga vira **erro de lint**, não frase que o
+agente relê a cada sessão. Um arquivo na raiz do app Next basta, e só usa o que o
+`eslint-config-next` já instala (typescript-eslint e eslint-plugin-import): nenhum plugin novo.
+
+## Arquivos
+
+Dependências (`npm i -D eslint@9 eslint-config-next typescript`). ESLint 9 é a faixa que
+`eslint-plugin-import` e `eslint-plugin-react` declaram como peer; o typescript-eslint do
+`eslint-config-next` pede TypeScript `<6.1`.
+
+No Next 16 o `next build` não roda mais o lint. O nó de build do `morph-spec verify` roda o
+eslint (`--quiet`: só erro reprova) **só nos arquivos que a feature mudou**, na raiz do app, quando
+acha `eslint.config.*` e o pacote `eslint` instalado: dívida de lint antiga nunca deixa a feature
+vermelha. As zonas são relativas a essa raiz.
+
+`eslint.config.mjs`:
+
+```js
+import { defineConfig, globalIgnores } from 'eslint/config'
+import nextVitals from 'eslint-config-next/core-web-vitals'
+import nextTs from 'eslint-config-next/typescript'
+
+const BANNED = [
+  [['framer-motion'], 'Motion entra por motion/react: um único caminho de import.'],
+  [['zustand', 'redux', '@reduxjs/toolkit'], 'Estado de servidor é do TanStack Query; página e filtro vão na URL.'],
+  [['pg', '@neondatabase/serverless', '@prisma/client', 'drizzle-orm', 'postgres'], 'O Next nunca fala com o banco: o dado vem da API .NET.'],
+]
+
+const DEEP_FEATURE = {
+  group: ['@/features/*/*'],
+  message: 'Fora da feature, importe a API pública (@/features/x), nunca um caminho interno.',
+}
+
+const restrictedImports = (...extraPatterns) => ['error', {
+  paths: [
+    ...BANNED.flatMap(([names, message]) => names.map((name) => ({ name, message }))),
+    { name: '@/components/ui/form', message: 'Form legado do shadcn: Controller + Field (frontend-nextjs-forms).' },
+  ],
+  patterns: [
+    ...BANNED.map(([names, message]) => ({ group: names.map((n) => `${n}/*`), message })),
+    ...extraPatterns,
+  ],
+}]
+
+const FETCH_IN_EFFECT = {
+  selector:
+    "CallExpression[callee.name='useEffect'] CallExpression:matches([callee.name='fetch'], [callee.name='apiClient'], [callee.object.name='apiClient'])",
+  message: 'Dado do servidor vem de Server Component ou TanStack Query, nunca de fetch em useEffect.',
+}
+
+export default defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores(['.next/**', 'out/**', 'build/**', 'next-env.d.ts']),
+  {
+    rules: {
+      'no-restricted-imports': restrictedImports(DEEP_FEATURE),
+      'import/no-restricted-paths': ['error', {
+        zones: [
+          { target: './src/components', from: './src/features', message: 'components/ é apresentação: não conhece feature.' },
+          { target: './src/features', from: './src/app', message: 'app/ importa de features/, nunca o contrário.' },
+          { target: './src/hooks', from: ['./src/lib/api-client.ts', './src/lib/api'], message: 'Hook compartilhado não chama API: isso é hook de feature.' },
+        ],
+      }],
+      'no-restricted-syntax': ['error', FETCH_IN_EFFECT],
+      'import/no-default-export': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      'no-console': 'warn',
+    },
+  },
+  {
+    files: ['src/features/**'],
+    rules: { 'no-restricted-imports': restrictedImports() },
+  },
+  {
+    files: ['app/layout.tsx', 'src/app/layout.tsx'],
+    rules: {
+      'no-restricted-syntax': ['error', FETCH_IN_EFFECT, {
+        selector: "Program > ExpressionStatement[directive='use client']",
+        message: "O layout raiz é Server Component (metadata): o 'use client' vai no provider que ele renderiza.",
+      }],
+    },
+  },
+  {
+    files: [
+      '**/app/**/{page,layout,loading,error,global-error,not-found,forbidden,unauthorized,template,default,route}.{ts,tsx}',
+      '**/app/**/{sitemap,robots,manifest,icon,apple-icon,opengraph-image,twitter-image}.{ts,tsx}',
+      '**/*.config.{js,mjs,cjs,ts}',
+    ],
+    rules: { 'import/no-default-export': 'off' },
+  },
+])
+```
+
+Cada override de `no-restricted-imports` e `no-restricted-syntax` substitui a lista inteira da
+regra naquele arquivo, por isso o bloco do layout repete `FETCH_IN_EFFECT` e o de `features/`
+repete os pacotes banidos.
+
+## O que cada regra compra
+
+| Regra | Bloqueia | Por quê |
+|---|---|---|
+| `no-restricted-imports` `@/features/*/*` (fora de `src/features/`) | `app/`, `components/` e `lib/` lendo arquivo interno de uma feature | o `index.ts` é a API pública: refatorar dentro da feature não quebra quem está fora |
+| `no-restricted-imports` `framer-motion` | o segundo caminho de import do Motion | `motion/react` e `framer-motion` juntos duplicam o runtime no bundle e dividem o código em duas APIs |
+| `no-restricted-imports` `zustand`, `redux`, `@reduxjs/toolkit` | store global | cópia do estado do servidor fica velha sem o cache do TanStack Query; página e filtro na URL sobrevivem a refresh e link |
+| `no-restricted-imports` `pg`, `@neondatabase/serverless`, `@prisma/client`, `drizzle-orm`, `postgres` | driver de banco no Next | regra de negócio e acesso a dados moram no .NET (EF Core); um segundo caminho ao banco pula a autorização dele |
+| `no-restricted-imports` `@/components/ui/form` | o `Form` legado do shadcn | a documentação do shadcn é escrita em `Controller` + `Field`; a tela legada migra quando é tocada |
+| `import/no-restricted-paths` `src/components` ↛ `src/features` | componente compartilhado que conhece domínio | ele deixa de ser compartilhável e cria ciclo feature → components → feature |
+| `import/no-restricted-paths` `src/features` ↛ `src/app` | feature importando rota | a dependência é de mão única: a rota compõe a feature |
+| `import/no-restricted-paths` `src/hooks` ↛ cliente da API | hook compartilhado chamando o backend | chamada à API é de feature, com a key factory dela; hook compartilhado é só de UI |
+| `no-restricted-syntax` fetch/`apiClient` dentro de `useEffect` | busca de dado no efeito | sem cache, sem dedup, corrida entre requisições e cascata de render; Server Component ou TanStack Query resolvem |
+| `no-restricted-syntax` `'use client'` em `app/layout.tsx` | layout raiz no cliente | perde `metadata` e manda a árvore inteira para o bundle do cliente |
+| `import/no-default-export` (exceto arquivos de rota e `*.config.*`) | `export default` em componente e hook | nome único em todo import: busca e rename acham todos os usos; o Next exige `default` só nos arquivos de convenção |
+| `@typescript-eslint/no-explicit-any` | `any` | desliga o tipo no ponto onde o dado da API entra; o certo é schema Zod + `z.infer` |
+| `no-console` (aviso) | `console.log` esquecido | ruído no console do usuário e dado vazando; aviso, porque o diagnóstico local é legítimo |
+
+Restrição nova entra como linha neste arquivo, com o porquê na `message`. Nunca uma regra nova
+em prosa. Exceção pontual é `// eslint-disable-next-line <regra> -- <motivo>` na linha, nunca o
+desligamento da regra no projeto.
+
+## O que não é regra
+
+Nome de classe CSS (BEM, prefixo de página, namespace `--app-`, sufixo de estado), catálogo de
+classes `.animate-*`/`.stagger-*`, `className` opcional em toda prop, Zod em props, quantos
+momentos de motion uma página tem, o deslocamento de uma transição, o skeleton com
+`animate-pulse`, os defaults de `staleTime`/`retry` do `QueryClient` e quantos níveis de prop
+drilling são aceitáveis são gosto: nem prosa nem lint. Siga o arquivo vizinho, e o formatter do
+projeto decide a forma. Também saíram da prosa o `'use client'` no `error.tsx` (o `next build`
+recusa sem ele) e o prefixo `use` do hook (o `react-hooks/rules-of-hooks` que vem no
+`eslint-config-next` acusa hook chamado fora de função `useX`).

package/framework/standards/frontend/nextjs/motion-patterns.md

@@ -221,14 +221,11 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 - `mode="wait"` ensures the exit animation completes before the entering page renders.
 - The `key` prop must change on navigation — use `usePathname()` from `next/navigation`.
-- Keep page transitions subtle (`y: 8`, fast duration) — aggressive transitions hurt perceived performance.
 
 ---
 
 ## Section 6: Loading Patterns
 
-Prefer CSS `animate-pulse` for skeleton loaders over Motion — CSS animations run off the main thread and have lower performance overhead.
-
 ```tsx
 // components/skeleton.tsx
 import { cn } from '@/lib/utils';
@@ -315,11 +312,8 @@ This CSS fallback catches animations outside Motion (Tailwind `animate-*`, third
 | `duration: 0.8` for UI interactions | `duration: durations.fast` (0.15) for micro-interactions |
 | Hardcoded easing `[0.4, 0, 0.2, 1]` | `ease: easings.standard` (from design-tokens) |
 | No `useReducedMotion()` check | Always check or use CSS media query |
-| Animating everything on the page | Reserve motion for 3-5 meaningful moments per page |
 | Forgetting `animation-fill-mode: backwards` in stagger | Will cause a flash before the animation starts |
 | `AnimatePresence` without `key` changes | Exit animations will never fire |
-| Using `motion` for skeleton loaders | Use CSS `animate-pulse` — lower performance cost |
-| `npm install framer-motion` / `import ... from 'framer-motion'` | `npm install motion` / `import ... from 'motion/react'` — same code underneath, but one import path per codebase |
 | Need ScrollTrigger, SVG morph, or complex timelines | Use GSAP — see `frontend/gsap/gsap-core.md` |
 
 ---
@@ -333,7 +327,8 @@ npm install motion
 > The package is `motion` and components import from `motion/react`. `framer-motion`
 > is not deprecated: it is published with the same version and `motion` depends on
 > it. New code still depends on `motion` and imports from `motion/react`, so the
-> codebase has a single import path; do not add `framer-motion` alongside it.
+> codebase has a single import path; a `framer-motion` import is a lint error
+> (`frontend-nextjs-lint`).
 
 Verify the installed version supports the features used here (requires motion >= 11; current major on npm is 14):
 

package/framework/standards/frontend/nextjs/naming-conventions.md

@@ -15,9 +15,9 @@ Consistent naming prevents filesystem bugs (Linux case-sensitivity) and keeps th
 
 - ALWAYS use kebab-case for file names — never PascalCase or camelCase
 - ALWAYS use PascalCase for React component exports
-- ALWAYS use camelCase starting with `use` for hook exports
 - ALWAYS suffix schema files with `.schemas.ts` and type files with `.types.ts`
 - NEVER mix cases in the same category — no `UserCard.tsx` alongside `user-profile.tsx`
+- Named exports, the hook `use` prefix and `default` only in route files are lint errors (`frontend-nextjs-lint`), not rules to reread
 
 ## Complete Reference Table
 
@@ -63,7 +63,6 @@ export type UpdateUserInput = z.infer<typeof updateUserSchema>;
 |-------|-------|-----|
 | `UserCard.tsx` | `user-card.tsx` | Linux servers are case-sensitive |
 | `useUsers.ts` | `use-users.ts` | Inconsistent with Next.js file conventions |
-| `export default function UserCard` | `export function UserCard` | Named exports are more refactor-safe |
 | `type User = { id: string }` | `type User = z.infer<typeof userSchema>` | Single source of truth |
 
 ---

package/framework/standards/frontend/nextjs/nextjs-patterns.md

@@ -16,7 +16,8 @@ Stack: Next.js 15 + Neon PostgreSQL + .NET Backend
 - ALWAYS use App Router (not Pages Router)
 - Default to Server Components -- add `'use client'` only when needed
 - ALWAYS colocate loading.tsx and error.tsx with page.tsx
-- NEVER call the database directly from client -- use Route Handlers as BFF
+- Route Handlers are a BFF that delegates to the .NET API
+- A DB driver, `any`, fetch inside `useEffect` and `'use client'` in the root layout are lint errors (`frontend-nextjs-lint`)
 - ALWAYS validate inputs with Zod on both client and server
 - Use TypeScript strict mode (`"strict": true`)
 
@@ -58,7 +59,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 // loading.tsx
 export default function Loading() { return <div className="animate-pulse">Loading...</div>; }
 
-// error.tsx — MUST be 'use client'
+// error.tsx
 'use client';
 export default function Error({ error, reset }: { error: Error; reset: () => void }) {
   return <div><h2>Something went wrong</h2><button onClick={reset}>Try again</button></div>;
@@ -187,7 +188,7 @@ export function DocumentForm() {
 
 ## shadcn/ui
 
-Install: `npx shadcn@latest init` then `npx shadcn@latest add button input card dialog form`.
+Install: `npx shadcn@latest init` then `npx shadcn@latest add button input card dialog field`.
 Components are copied to `components/ui/` -- NOT an npm dependency, your code to customize.
 
 ## TypeScript Strict Patterns
@@ -195,7 +196,7 @@ Components are copied to `components/ui/` -- NOT an npm dependency, your code to
 | Pattern | Approach |
 |---------|----------|
 | API responses | Zod schema + `z.infer<typeof schema>` |
-| Props | Explicit interface, no `any` |
+| Props | Explicit interface |
 | Event handlers | `React.ChangeEvent<HTMLInputElement>` |
 | Null safety | `?.` over type assertions, `if (!data) return null` |
 
@@ -204,10 +205,7 @@ Components are copied to `components/ui/` -- NOT an npm dependency, your code to
 | Wrong | Right | Why |
 |-------|-------|-----|
 | `'use client'` on every component | Default to Server Components | Unnecessary JS bundle size |
-| Direct DB from client | Route Handler `/api/*` as BFF | Exposes queries, harder to secure |
-| `any` for API responses | Zod schema + infer | No runtime safety |
 | Missing loading.tsx | Colocate with page.tsx | Blank page during load |
-| `useEffect` for data fetching | React Query `useQuery` | No caching, race conditions |
 | Form validation on submit only | Zod resolver + react-hook-form | Delayed error feedback |
 | shadcn as npm package | `npx shadcn@latest add` | Copy-paste system, not a dependency |
 

package/framework/standards/frontend/nextjs/project-structure.md

@@ -14,10 +14,11 @@ Feature-based architecture with a shared core. Features are self-contained; shar
 ## Core Rules
 
 - ALWAYS use feature-based folders: `features/{feature-name}/`
-- ALWAYS keep `app/` for routing only — import from `features/`, not the other way
+- ALWAYS keep `app/` for routing only — the screen's logic lives in `features/`
 - NEVER import from one feature into another — extract to `components/` or `lib/` if shared
 - ALWAYS use `src/` directory (configured in `tsconfig.json` with `@/` alias)
 - NEVER put business logic in `components/` — it is presentation only
+- Deep imports into a feature from outside it, `components/` → `features/`, `features/` → `app/` and shared `hooks/` → the API client are lint errors (`frontend-nextjs-lint`)
 
 ## Canonical Folder Tree
 
@@ -82,7 +83,7 @@ export { useCreateUser } from './hooks/use-create-user';
 export type { User, CreateUserInput } from './types/user.types';
 ```
 
-Import from the index, not deep paths:
+Outside the feature, import from the index:
 ```ts
 // GOOD
 import { UserList, useUsers } from '@/features/users';

package/framework/standards/frontend/nextjs/state-management.md

@@ -16,7 +16,7 @@ Server state (API data) lives in TanStack Query. UI state lives in React. No glo
 - ALWAYS use TanStack Query for anything that comes from the .NET API
 - ALWAYS use `useState` for local UI state (modal open, form step)
 - ALWAYS keep a list's page, sort and filters, and a page's active tab, in the URL (`searchParams`) — never in `useState`: a refresh or a shared link must reopen the same view (`admin-app/data-table.md`, `admin-app/page-structure.md`)
-- NEVER install Zustand or Redux without first exhausting Server Components + TanStack Query
+- `zustand`, `redux` and `@reduxjs/toolkit` are lint errors (`frontend-nextjs-lint`); the only way past it is the exception below
 - NEVER use React Context for server state — Context does not cache or deduplicate
 - ALWAYS derive state from server data rather than syncing it to local state
 
@@ -30,9 +30,9 @@ Is this local UI state (open/closed, selected, current step)?
   YES → useState in the component that needs it
 
 Does multiple components need this UI state?
-  YES — is it parent-child?     → prop drilling (2-3 levels is fine)
+  YES — is it parent-child?     → props
   YES — is it truly global?     → React Context (theme, auth user, locale)
-  YES — complex with many actions? → Consider Zustand (last resort)
+  YES — complex with many actions? → global store (exception below)
 ```
 
 ## Server State (TanStack Query)
@@ -55,9 +55,10 @@ function UserList() {
 }
 ```
 
-## When Zustand Is Justified
+## When a Global Store Is Justified
 
-Only add Zustand if ALL of these are true:
+The lint blocks the import. Lift it only if ALL of these are true, with one
+`// eslint-disable-next-line no-restricted-imports -- <reason>` in the single store file:
 1. State is needed in 5+ unrelated components
 2. State has complex update logic (not just toggle/set)
 3. Context causes measurable re-render performance issues
@@ -67,10 +68,8 @@ Only add Zustand if ALL of these are true:
 
 | Wrong | Right | Why |
 |-------|-------|-----|
-| `useEffect` + `useState` for API data | TanStack Query | Stale data, no cache, double-render |
 | Global store for user list | `useUsers()` | TanStack Query handles sync/cache |
 | Context for everything | useState + prop drilling first | Context causes all consumers to re-render |
-| Zustand by default | Start with useState | YAGNI — most state is local |
 
 ---
 

package/framework/standards/infrastructure/docker/local-compose-isolation.md

@@ -96,5 +96,6 @@ volumes:
 ```bash
 # inside the worktree, outside Claude Code
 eval "$(morph-spec env)"        # PowerShell: morph-spec env --powershell | Invoke-Expression
+                                # --with-secrets also loads the e2e.auth.envFile credentials
 docker compose up -d --wait     # lands in project morph-{feature}, on the block's ports
 ```

package/framework/templates/README.md

@@ -8,8 +8,8 @@
 nextjs) rather than by stack. A template for a .NET slice serves every stack with a .NET
 backend, so a new stack reuses what exists instead of copying it.
 
-`REGISTRY.json` is the source of truth: it maps each template `id` to its `path`, category,
-technology and applicable stacks. Nothing resolves a template by hardcoded path — code goes
+`REGISTRY.json` is the source of truth: it maps each template `id` to its `kind`, `path` and
+`category` (the shape per kind is in its `kinds` block). Nothing resolves a template by hardcoded path — code goes
 through the registry, and this README never repeats a path the registry already owns.
 
 ---
@@ -109,8 +109,8 @@ updates** — only override when the packaged template genuinely does not fit.
 1. Create the file under the right technology directory:
    `framework/templates/code/{technology}/...` (Handlebars syntax, `.hbs` when the extension
    would otherwise confuse tooling).
-2. Register it in `REGISTRY.json` with a unique `id`, its `path`, `category`, `technology`
-   and applicable stacks.
+2. Register it in `REGISTRY.json` with a unique `id`, its `kind`, `path` and `category`, plus
+   the fields its kind requires (`kinds` block; `scripts/validate-framework.js` checks them).
 3. If a generator should emit it, add the `id` to the relevant list in
    `src/lib/generators/scaffold-generator.js`.