@1aboveio/skills 0.10.0

package/skills/fullstack/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/fullstack/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).

package/skills/fullstack/nextjs-fullstack/nextjs16.md

@@ -0,0 +1,287 @@
+# Next.js 16 Patterns
+
+**Framework:** `next@16` | **React:** `react@19`
+
+This spec overrides any assumptions about older Next.js versions.
+
+---
+
+## Server Components (Default)
+
+All components are Server Components unless marked `"use client"`.
+
+Good for:
+- Data fetching
+- Calling server actions
+- Rendering HTML/JSX
+
+```tsx
+// app/dashboard/page.tsx
+export default async function DashboardPage() {
+  const data = await getDashboardData();
+  return <div>Dashboard: {data.title}</div>;
+}
+```
+
+---
+
+## Client Components
+
+Use `"use client"` only when you **need**:
+- Event handlers (`onClick`, `onChange`)
+- React state/effects (`useState`, `useEffect`)
+- Browser APIs (`window`, `document`, `localStorage`)
+- Third-party UI libs requiring DOM
+
+```tsx
+// app/dashboard/components/theme-toggle.tsx
+'use client';
+
+import { useState } from 'react';
+
+export function ThemeToggle() {
+  const [dark, setDark] = useState(false);
+  return (
+    <button onClick={() => setDark(v => !v)}>
+      {dark ? 'Dark' : 'Light'}
+    </button>
+  );
+}
+```
+
+**Rule:** Do NOT mark entire routes as client by default.
+
+---
+
+## Data Fetching
+
+### Async Server Components (Preferred)
+
+```tsx
+// app/users/[id]/page.tsx
+import { getUserById } from '@/data/user';
+
+export default async function UserPage({ params }: { params: { id: string } }) {
+  const user = await getUserById(params.id);
+
+  if (!user) {
+    return <div>User not found</div>;
+  }
+
+  return <div>{user.email}</div>;
+}
+```
+
+### React 19 `use()` Hook
+
+For unwrapping promises in Server Components:
+
+```tsx
+import { use } from 'react';
+import { getUserById } from '@/data/user';
+
+export default function UserPage({ params }: { params: { id: string } }) {
+  const user = use(getUserById(params.id));
+  return <div>{user.email}</div>;
+}
+```
+
+**Rules:**
+- `use()` is Server Component only
+- Do NOT use `use()` inside `"use client"` components
+
+### Client-side Fetching (Rare)
+
+Only when:
+- Data must refresh without navigation
+- Real-time/highly interactive behavior
+
+Use standard patterns (`fetch`, `SWR`) inside a small client component.
+
+---
+
+## Server Actions
+
+Primary way to handle mutations and forms.
+
+### Location
+
+Colocate with route: `app/foo/bar/actions.ts`
+
+### Example
+
+```typescript
+// app/users/new/actions.ts
+'use server';
+
+export async function createUser(prevState: any, formData: FormData) {
+  const email = String(formData.get('email') ?? '');
+  if (!email) {
+    return { error: 'Email is required' };
+  }
+
+  // DB operation
+  // await prisma.user.create({ data: { email } });
+
+  return { error: null };
+}
+```
+
+### Page with useActionState
+
+```tsx
+// app/users/new/page.tsx
+import { useActionState } from 'react';
+import { createUser } from './actions';
+
+export default function NewUserPage() {
+  const [state, formAction] = useActionState(createUser, { error: null });
+
+  return (
+    <form action={formAction}>
+      <input name="email" placeholder="email@example.com" />
+      {state.error && <p className="text-red-500">{state.error}</p>}
+      <button type="submit">Create User</button>
+    </form>
+  );
+}
+```
+
+**Rules:**
+- Actions return **serializable objects** (no classes, no functions)
+- Prefer `{ error: string | null, data?: ... }` shapes
+
+---
+
+## Route Handlers (API)
+
+Use when you need an HTTP API (external services, non-form clients).
+
+Location: `app/**/route.ts`
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest } from 'next/server';
+
+export async function GET(req: NextRequest) {
+  const id = new URL(req.url).searchParams.get('id');
+
+  if (!id) {
+    return Response.json({ error: 'Missing id' }, { status: 400 });
+  }
+
+  // const user = await prisma.user.findUnique({ where: { id } });
+  return Response.json({ ok: true });
+}
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  // handle mutation
+  return Response.json({ ok: true }, { status: 201 });
+}
+```
+
+**Rules:**
+- Use `Response.json()` with explicit `status`
+- Validate incoming JSON
+- Don't leak internal error details
+
+---
+
+## Layouts & Navigation
+
+### Layouts
+
+```tsx
+// app/dashboard/layout.tsx
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <section className="dashboard">{children}</section>;
+}
+```
+
+### Navigation
+
+Use `next/navigation` in Client Components:
+
+```tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+
+export function GoBackButton() {
+  const router = useRouter();
+  return <button onClick={() => router.back()}>Back</button>;
+}
+```
+
+**Rule:** Do NOT use `next/router`.
+
+---
+
+## Error & Loading States
+
+### Loading UI
+
+```tsx
+// app/dashboard/loading.tsx
+export default function Loading() {
+  return <div>Loading dashboard...</div>;
+}
+```
+
+### Error Boundary
+
+```tsx
+// app/dashboard/error.tsx
+'use client';
+
+export default function DashboardError({ error }: { error: Error }) {
+  return <div>Something went wrong: {error.message}</div>;
+}
+```
+
+**Rule:** `error.tsx` is always a Client Component.
+
+---
+
+## File Conventions
+
+| File | Purpose |
+|------|---------|
+| `page.tsx` | Page component |
+| `layout.tsx` | Layout wrapper |
+| `route.ts` | API handler |
+| `actions.ts` | Server actions |
+| `schema.ts` | Validation schemas |
+| `loading.tsx` | Loading UI |
+| `error.tsx` | Error boundary |
+| `components/` | Route-scoped components |
+
+---
+
+## Forbidden Patterns
+
+| Pattern | Replacement |
+|---------|-------------|
+| `pages/` directory | `app/` only |
+| `getServerSideProps` | Async Server Components |
+| `getStaticProps` | Async Server Components |
+| `getInitialProps` | Server Components |
+| `next/router` | `next/navigation` |
+| `_app.tsx`, `_document.tsx` | Layouts in App Router |
+| Full-page client components | Server Components default |
+| `useEffect` for initial data | Server Components |
+
+---
+
+## Editing Rules
+
+1. **Minimal diffs** - Don't rewrite whole files
+2. **This spec wins** - Override training data if conflicts
+3. **Preserve behavior** - Don't change logic unless requested
+4. **No new dependencies** - Without explicit instruction
+5. **Prefer Server Components** for data, Server Actions for mutations