@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/app-dev/nextjs-fullstack/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: nextjs-fullstack
+description: "Build or debug Next.js App Router features with React 19 — pages/layouts/route handlers, Server/Client Components, Server Actions, forms, middleware, DAL, strict TypeScript, Zod — plus our conventions: nuqs URL state, SWR cache, Skeleton/Progress + Sonner feedback, drag-and-drop upload, the portal app shell, list pages as filter/sort/paginate tables. shadcn component mechanics: see the shadcn skill."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Next.js 16 Fullstack Development
+
+**Stack:** Next.js 16 (App Router) | React 19 | TypeScript strict | Zod | Prisma
+
+## Quick Reference
+
+- [Architectural Conventions](conventions.md) - Layers, DAL, testing
+- [Next.js 16 Patterns](nextjs16.md) - App Router, components, routing
+- [Server Actions & Forms](server-actions.md) - useActionState, withCallbacks
+- [Frontend Conventions](frontend-conventions.md) - nuqs URL state, SWR cache, feedback (Progress/Sonner), file upload, portal app shell, i18n, list pages (components → `shadcn`)
+
+---
+
+## Core Principles
+
+1. **Server Components by default** - Client Components only when needed
+2. **Server Actions for mutations** - Not API routes for forms
+3. **DAL for database access** - Never call Prisma from components
+4. **Zod for validation** - At server action boundary
+5. **TypeScript strict mode** - Explicit return types on exports
+
+---
+
+## Project Structure
+
+```
+src/
+├── app/
+│   ├── layout.tsx
+│   ├── page.tsx
+│   ├── (public)/...           # Public routes
+│   ├── dashboard/
+│   │   ├── layout.tsx
+│   │   ├── page.tsx
+│   │   ├── settings/
+│   │   │   ├── page.tsx
+│   │   │   ├── actions.ts     # Route-scoped server actions
+│   │   │   ├── schema.ts      # Route-scoped validation
+│   │   │   └── components/
+│   │   └── [id]/
+│   │       └── page.tsx
+│   └── api/
+│       └── health/
+│           └── route.ts
+├── lib/
+│   ├── auth.ts                # Auth configuration
+│   ├── prisma.ts              # Database client
+│   └── server-action.ts       # Action utilities
+├── dal/
+│   └── user.ts                # Data access layer
+├── components/
+│   ├── ui/                    # Shared primitives
+│   └── client/                # Reusable client components
+└── context/
+    └── session-context.tsx
+```
+
+---
+
+## Architectural Layers
+
+### 1. UI Layer (Components & Pages)
+
+- Location: `app/**`, `components/**`
+- Renders UI (RSC or client components)
+- Calls server actions (via import or `useActionState`)
+- No direct Prisma usage
+
+### 2. Use Case Layer (Server Actions)
+
+- Location: `app/**/actions.ts`
+- Always begins with `'use server'`
+- Validates input with Zod
+- Enforces auth and permissions
+- Calls DAL for database operations
+- Returns typed `ActionResult` shape
+
+### 3. Data Access Layer (DAL)
+
+- Location: `lib/repositories/**` or `dal/**`
+- All Prisma access
+- Framework-agnostic (no Next.js, no auth)
+- Returns domain objects or `null`
+- No Zod schemas, no logging
+
+---
+
+## Server Action Pattern
+
+```typescript
+// app/dashboard/settings/actions.ts
+'use server';
+
+import { z } from 'zod';
+import { revalidatePath } from 'next/cache';
+import { auth } from '@/lib/auth';
+import { updateUserProfile } from '@/dal/user';
+
+const schema = z.object({
+  name: z.string().min(1).max(50),
+  avatarUrl: z.string().url().optional(),
+});
+
+export type ActionResult<T = unknown> = {
+  success: boolean;
+  data?: T;
+  error?: { code: string; message: string };
+};
+
+export async function updateProfile(input: unknown): Promise<ActionResult> {
+  const session = await auth();
+  if (!session?.user) {
+    return { success: false, error: { code: 'UNAUTHENTICATED', message: 'Please sign in.' } };
+  }
+
+  const parsed = schema.safeParse(input);
+  if (!parsed.success) {
+    return { success: false, error: { code: 'VALIDATION_ERROR', message: 'Invalid input.' } };
+  }
+
+  try {
+    const user = await updateUserProfile(session.user.id, parsed.data);
+    revalidatePath('/dashboard/settings');
+    return { success: true, data: user };
+  } catch (err) {
+    console.error(err);
+    return { success: false, error: { code: 'INTERNAL_ERROR', message: 'Something went wrong.' } };
+  }
+}
+```
+
+---
+
+## Client Component with useActionState
+
+```tsx
+'use client';
+
+import { startTransition, useActionState } from 'react';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { toast } from 'sonner';
+import { updateProfile } from './actions';
+
+export function ProfileForm() {
+  const { register, handleSubmit } = useForm({
+    resolver: zodResolver(schema),
+  });
+
+  const [state, formAction, isPending] = useActionState(
+    async (prev, data) => {
+      const result = await updateProfile(data);
+      if (result.success) toast.success('Profile updated');
+      else toast.error(result.error?.message);
+      return result;
+    },
+    { success: false }
+  );
+
+  function onSubmit(data) {
+    startTransition(() => formAction(data));
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('name')} />
+      <button disabled={isPending}>Save</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Forbidden Patterns
+
+| Pattern | Why |
+|---------|-----|
+| `pages/` directory | App Router only |
+| `getServerSideProps`, `getStaticProps` | Use Server Components |
+| `next/router` | Use `next/navigation` |
+| Full-page client components | Bad perf |
+| Fetching data with `useEffect` | Use Server Components |
+| Direct Prisma in components | Use DAL |
+| `HTTPException` from DAL | Keep DAL framework-agnostic |
+
+---
+
+## Do / Don't
+
+### Do
+
+- Use `'use server'` actions as use-case boundaries
+- Validate inputs with Zod before DB/auth logic
+- Route all Prisma through repositories/DAL
+- Return consistent `ActionResult` shapes
+- Use explicit TS types for exports
+
+### Don't
+
+- Don't call Prisma from components or actions directly
+- Don't access auth inside DAL
+- Don't return raw errors to client
+- Don't put business logic in DAL
+- Don't skip input validation

package/skills/app-dev/nextjs-fullstack/conventions.md

@@ -0,0 +1,318 @@
+# Architectural Conventions
+
+## Directory & Naming
+
+### DB Client
+
+`lib/db/client.ts` or `lib/prisma.ts`:
+- Export singleton Prisma client
+- Standard safeguards for dev hot-reload
+
+### Repositories / DAL
+
+Location: `lib/repositories/` or `dal/`
+
+```
+lib/repositories/
+├── userRepository.ts
+├── orderRepository.ts
+└── index.ts
+```
+
+Naming: `<entity>Repository.ts`
+Functions: `getUserById`, `listOrdersByUser`, `createOrder`
+
+### Server Actions
+
+Group by feature:
+
+```
+app/(dashboard)/settings/actions.ts
+app/(shop)/orders/[orderId]/actions.ts
+```
+
+Export named actions:
+- `export async function updateProfile(...)`
+- `export async function createOrder(...)`
+
+### Schemas & Types
+
+- Shared Zod schemas: `lib/schemas/**`
+- Domain types/DTOs: `lib/types/**`
+
+---
+
+## TypeScript Rules
+
+- `strict: true` in `tsconfig.json`
+- All **exported** functions must have explicit return types
+- Prefer **type aliases** over interfaces for simple data shapes
+- Use `async`/`await`, avoid `.then/.catch` chaining
+- Prefer **named exports** for repositories, actions, helpers
+
+### Error Types
+
+Define in `lib/errors.ts`:
+
+```typescript
+export class NotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class PermissionDeniedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PermissionDeniedError';
+  }
+}
+```
+
+---
+
+## Server Actions - Detailed
+
+### File Setup
+
+```typescript
+'use server';
+
+import { z } from 'zod';
+import { auth } from '@/lib/auth';
+import { userRepository } from '@/lib/repositories';
+import { NotFoundError, PermissionDeniedError } from '@/lib/errors';
+```
+
+### Input Validation
+
+Always use Zod:
+
+```typescript
+const schema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+});
+
+export async function updateUser(input: unknown) {
+  const parsed = schema.safeParse(input);
+  if (!parsed.success) {
+    return { success: false, error: { code: 'VALIDATION_ERROR', message: parsed.error.message } };
+  }
+  // ...
+}
+```
+
+### Auth Pattern
+
+```typescript
+const session = await auth();
+if (!session?.user) {
+  return {
+    success: false,
+    error: { code: 'UNAUTHENTICATED', message: 'Please sign in.' },
+  };
+}
+
+// For permissions
+if (session.user.role !== 'ADMIN') {
+  return { success: false, error: { code: 'FORBIDDEN', message: 'Admins only.' } };
+}
+```
+
+### Standard Response Shape
+
+```typescript
+export type ActionError = {
+  code: string;
+  message: string;
+};
+
+export type ActionResult<TData = unknown> = {
+  success: boolean;
+  data?: TData;
+  error?: ActionError;
+};
+```
+
+### Error Mapping
+
+```typescript
+try {
+  const data = await someRepositoryCall(...);
+  if (!data) {
+    return { success: false, error: { code: 'NOT_FOUND', message: 'Resource not found.' } };
+  }
+  return { success: true, data };
+} catch (err) {
+  if (err instanceof PermissionDeniedError) {
+    return { success: false, error: { code: 'FORBIDDEN', message: err.message } };
+  }
+  console.error(err);
+  return { success: false, error: { code: 'INTERNAL_ERROR', message: 'Something went wrong.' } };
+}
+```
+
+---
+
+## Data Access Layer (Prisma)
+
+### General Rules
+
+- No Next.js imports (`next/headers`, etc.)
+- No auth logic - DAL is unaware of current user
+- No Zod schemas - inputs already validated
+- No logging - callers decide when to log
+
+### Repository Functions
+
+```typescript
+// lib/repositories/userRepository.ts
+import { db } from '../db/client';
+import type { User } from '@prisma/client';
+
+export async function getUserById(userId: string): Promise<User | null> {
+  return db.user.findUnique({
+    where: { id: userId },
+  });
+}
+
+export async function updateUserProfile(
+  userId: string,
+  data: { name?: string | null; avatarUrl?: string | null }
+): Promise<User> {
+  return db.user.update({
+    where: { id: userId },
+    data,
+  });
+}
+```
+
+### Transactions
+
+```typescript
+export async function createOrderWithItems(args: { ... }): Promise<Order> {
+  return db.$transaction(async (tx) => {
+    const order = await tx.order.create({ ... });
+    await tx.orderItem.createMany({ ... });
+    return order;
+  });
+}
+```
+
+### Handling "Not Found"
+
+- For queries: Return `null`
+- For update/delete: Let Prisma throw, use-case layer catches and maps to NOT_FOUND
+
+---
+
+## Auth Integration (Better Auth)
+
+- Use auth **only in server actions/API routes**
+- Load session/user, enforce roles/permissions
+- Do **not** pass auth/session objects into DAL
+- Pass only **primitive IDs** (userId, tenantId) to repositories
+
+---
+
+## Testing Conventions
+
+### Unit Tests (Vitest)
+
+- Scope: Single function in isolation
+- Location: `<filename>.test.ts` alongside source
+- Mock all external dependencies
+- Follow AAA: Arrange, Act, Assert
+
+```typescript
+// lib/utils/formatCurrency.test.ts
+import { describe, it, expect } from 'vitest';
+import { formatCurrency } from './formatCurrency';
+
+describe('formatCurrency', () => {
+  it('should format positive numbers', () => {
+    expect(formatCurrency(1234.56, 'USD')).toBe('$1,234.56');
+  });
+});
+```
+
+### Integration Tests
+
+- Scope: Server actions with mocked database
+- Location: `<feature>/actions.test.ts`
+- Test full flow: validation -> auth -> logic -> response
+
+```typescript
+// app/(dashboard)/settings/actions.test.ts
+import { describe, it, expect, vi } from 'vitest';
+import { updateProfile } from './actions';
+import * as userDal from '@/dal/user';
+import * as auth from '@/lib/auth';
+
+vi.mock('@/dal/user');
+vi.mock('@/lib/auth');
+
+describe('updateProfile', () => {
+  it('should return UNAUTHENTICATED when no session', async () => {
+    vi.mocked(auth.auth).mockResolvedValue(null);
+    const result = await updateProfile({ name: 'Test' });
+    expect(result.success).toBe(false);
+    expect(result.error?.code).toBe('UNAUTHENTICATED');
+  });
+});
+```
+
+### E2E Tests (Playwright)
+
+- Location: `e2e/` at project root
+- Focus on critical user journeys
+- Use `data-testid` attributes
+- Use Page Object Model for selectors
+
+```typescript
+// e2e/auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('should allow sign in', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByTestId('email-input').fill('test@example.com');
+  await page.getByTestId('password-input').fill('password123');
+  await page.getByTestId('submit-button').click();
+  await expect(page).toHaveURL('/dashboard');
+});
+```
+
+### Test Organization
+
+```
+├── lib/utils/
+│   ├── formatCurrency.ts
+│   └── formatCurrency.test.ts     # Unit
+├── dal/
+│   ├── user.ts
+│   └── user.test.ts               # Integration
+├── app/(dashboard)/settings/
+│   ├── actions.ts
+│   └── actions.test.ts            # Integration
+└── e2e/
+    ├── auth.spec.ts               # E2E
+    └── fixtures/
+        └── auth.ts
+```
+
+### Testing Do / Don't
+
+**Do:**
+- Write unit tests for utilities
+- Write integration tests for server actions
+- Use `data-testid` for E2E
+- Mock external dependencies
+- Keep tests deterministic
+
+**Don't:**
+- Don't test implementation details
+- Don't duplicate coverage in E2E
+- Don't use `sleep()` in E2E
+- Don't share mutable state between tests

package/skills/app-dev/nextjs-fullstack/frontend-conventions.md

@@ -0,0 +1,61 @@
+# Frontend Conventions (UI, state, feedback)
+
+Our preferences for building UI in this stack — *which patterns we reach for and why*. The **components themselves come from the `shadcn` skill** (component selection + composition rules); this file is the convention layer on top. Server/data architecture lives in [conventions.md](conventions.md) and [server-actions.md](server-actions.md).
+
+> When a convention needs a component, defer to `shadcn`. When it needs a Server Action / DAL / auth, defer to this skill's core.
+
+## URL state — `nuqs`
+
+Prefer **URL search params (via `nuqs`)** for any UI state that should be shareable, refresh-safe, or readable on the server: list **filters, sort, pagination**, tab selection, search queries, and "open panel/dialog" state.
+
+- **Why:** in the App Router, `searchParams` is readable in an RSC, so the server can filter/sort/paginate and the page is linkable and refresh-safe. Local `useState` for these loses on refresh and can't be server-rendered.
+- Keep genuinely ephemeral state (hover, focus, uncommitted form text) in React state — not everything belongs in the URL.
+- **Setup:** wrap the app once in `NuqsAdapter` (`nuqs/adapters/next/app`) in the root layout. Parse on the server with the `nuqs` server parsers; read/write on the client with `useQueryState` / `useQueryStates`.
+- This is the same URL-state layer the data table uses → `shadcn` → `rules/data-table.md`.
+
+## Data fetching & cache — RSC first, **SWR** for client
+
+- **Default:** fetch on the server (RSC / DAL), mutate via Server Actions — no client fetch.
+- **When you genuinely need client fetching** (polling, infinite scroll, data that changes outside the request, client-only widgets), use **SWR** for caching/revalidation.
+- **Why:** SWR gives stale-while-revalidate, request dedup, and focus revalidation without hand-rolling a cache — but it's the *exception*, not the default (see [Core Principles](SKILL.md)).
+- After a Server Action mutates server data, prefer `revalidatePath` / `revalidateTag`; call SWR `mutate()` only for client-cached keys.
+
+## Async feedback — Progress/Skeleton for reads, **Sonner** for writes
+
+- **Reads (queries / navigation / loading):** show a **Skeleton** or **Progress** placeholder (and `loading.tsx` / `Suspense` at route level). Never a toast for "loading."
+- **Writes (mutations / Server Actions):** report the *result* with a **Sonner** toast — `toast.success(...)` on success, `toast.error(result.error?.message)` on failure (the `ActionResult` shape in [server-actions.md](server-actions.md)). Pair with the button's `isPending` for the in-flight state.
+- **Why:** loading is a *state of the page* → inline placeholder; a mutation result is a *transient event* → toast. Mixing them (toast for loading, inline text for a save result) reads wrong.
+- Components (`Skeleton` / `Progress` / `Spinner` / `sonner`) are shadcn — see its "Feedback" selection + composition rules.
+
+## File upload — drag-and-drop dropzone
+
+- Prefer a **drag-and-drop dropzone** (with a click-to-browse fallback) over a bare `<input type="file">`.
+- **Component:** use the shadcn-registry dropzone / file-upload component → `shadcn` skill (add via its CLI, then fix imports to the project aliases).
+- **Upload handling:** send to a **Server Action** or a `route.ts` handler; validate type/size with **Zod** at the boundary; store via the project's storage client. Show per-file **Progress** and a **Sonner** toast on done/fail.
+- Keep the upload action in the use-case layer (`actions.ts`) and the storage call in a `lib` client — same layering as [conventions.md](conventions.md).
+
+## Portal app shell — sidebar + header
+
+The standard layout for an authenticated portal/dashboard:
+
+- **Sidebar** for primary navigation (collapsible) — the shadcn `Sidebar` block.
+- **Header**, right-aligned, carries three controls: a **theme toggle**, a **locale (i18n) switcher**, and a **profile menu** (`DropdownMenu`) showing the signed-in user + sign-out.
+  - Profile data + sign-out come from the **session (better-auth)** — load the session in the **RSC layout** and pass primitives down; don't fetch it client-side.
+  - Theme toggle via `next-themes`; the i18n switcher drives the locale → see [Internationalization](#internationalization-i18n) below.
+- Put the shell in a **route-group layout** (e.g. `app/(portal)/layout.tsx`) so every portal page inherits sidebar + header.
+- The components (Sidebar, DropdownMenu, Button) and their composition rules live in `shadcn`; this is just the *arrangement we standardize on*.
+
+## Internationalization (i18n)
+
+When the app is multi-locale:
+
+- **Library:** use an App Router–native i18n library (e.g. `next-intl`) so messages are **server-readable in RSC**, not a client-only context that re-renders the tree.
+- **Locale routing:** prefer a `[locale]` route segment (`app/[locale]/...`) — the locale is in the URL, so it's shareable, server-rendered, and SEO-correct. Middleware negotiates and redirects to a default locale.
+- **Messages:** per-locale catalogs (e.g. `messages/en.json`, `messages/zh.json`), namespaced by feature (not one flat file); load the active locale once in the root layout and provide it.
+- **The header switcher** (the i18n button in the app shell) changes the active locale by pushing the new `[locale]` segment (or a locale cookie). If you keep locale as a search param instead of a segment, that's the [URL state](#url-state--nuqs) convention.
+- **Translate at the edges, not in the DAL:** the DAL/use-case layer returns stable keys and data; UI resolves copy via the i18n hook / `getTranslations`. Don't bake localized strings into Server Actions or repositories (keeps the DAL framework-agnostic, per [conventions.md](conventions.md)).
+
+## List / index pages
+
+- Default to a **data table with filter + sort + pagination** for any portal list/index page (users, orders, records…), **not** a hand-rolled list — and drive its state through URL params (`nuqs`, above) so it's server-rendered and shareable.
+- **Implementation:** `shadcn` → `rules/data-table.md` (DiceUI `@diceui/data-table` for server-side; plain `Table` only for a trivial static list).