@folpe/loom 0.1.0 → 0.3.0

package/data/skills/i18n-patterns/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: i18n-patterns
+description: "Internationalization with next-intl for RSC, Server Actions, and Zod messages. Use when adding multi-language support, translating user-facing strings, or implementing locale-aware validation."
+---
+
+# I18n Patterns
+
+## Critical Rules
+
+- **All user-facing strings must be translated** — no hardcoded text in components.
+- **Use namespaces** — group translations by feature/page.
+- **Server-side `getTranslations`** — use in RSC and Server Actions.
+- **Client-side `useTranslations`** — use in Client Components only.
+- **Validation messages are translated** — use i18n error map with Zod.
+- **ICU message syntax** for plurals and interpolation: `"{count, plural, one {# item} other {# items}}"`.
+
+## Setup with next-intl
+
+### Configuration
+
+```ts
+// src/i18n/config.ts
+export const locales = ["en", "fr", "de"] as const;
+export type Locale = (typeof locales)[number];
+export const defaultLocale: Locale = "en";
+```
+
+### Message Files
+
+```
+messages/
+  en.json
+  fr.json
+  de.json
+```
+
+Structure messages by namespace:
+
+```json
+{
+  "common": {
+    "save": "Save",
+    "cancel": "Cancel",
+    "delete": "Delete",
+    "loading": "Loading..."
+  },
+  "auth": {
+    "login": "Sign in",
+    "logout": "Sign out",
+    "register": "Create account"
+  },
+  "users": {
+    "title": "Users",
+    "create": "Create user",
+    "name": "Name",
+    "email": "Email"
+  },
+  "validation": {
+    "required": "This field is required",
+    "email.invalid": "Please enter a valid email",
+    "too_small": "Must be at least {minimum} characters",
+    "too_big": "Must be at most {maximum} characters"
+  }
+}
+```
+
+## Server Components (RSC)
+
+```tsx
+import { getTranslations } from "next-intl/server";
+
+export default async function UsersPage() {
+  const t = await getTranslations("users");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1>
+      <Button>{t("create")}</Button>
+    </div>
+  );
+}
+```
+
+## Client Components
+
+```tsx
+"use client";
+import { useTranslations } from "next-intl";
+
+export function UserForm() {
+  const t = useTranslations("users");
+
+  return <label>{t("name")}</label>;
+}
+```
+
+## Server Actions with I18n
+
+Pass locale context to server actions for localized error messages:
+
+```ts
+// src/actions/user.actions.ts
+"use server";
+import { getLocale, getTranslations } from "next-intl/server";
+
+export async function createUser(input: unknown) {
+  const t = await getTranslations("validation");
+  const locale = await getLocale();
+
+  const schema = z.object({
+    name: z.string().min(2, t("too_small", { minimum: 2 })),
+    email: z.string().email(t("email.invalid")),
+  });
+
+  const parsed = schema.safeParse(input);
+  if (!parsed.success) {
+    return { success: false, error: parsed.error.errors[0].message };
+  }
+  // ...
+}
+```
+
+## Zod Validation with I18n
+
+### Custom Error Map
+
+```ts
+// src/lib/zod-i18n.ts
+import { z } from "zod";
+
+export function createI18nErrorMap(
+  t: (key: string, params?: Record<string, unknown>) => string
+): z.ZodErrorMap {
+  return (issue, ctx) => {
+    switch (issue.code) {
+      case z.ZodIssueCode.too_small:
+        if (issue.type === "string") {
+          return { message: t("too_small", { minimum: issue.minimum }) };
+        }
+        break;
+      case z.ZodIssueCode.too_big:
+        if (issue.type === "string") {
+          return { message: t("too_big", { maximum: issue.maximum }) };
+        }
+        break;
+      case z.ZodIssueCode.invalid_string:
+        if (issue.validation === "email") {
+          return { message: t("email.invalid") };
+        }
+        break;
+      case z.ZodIssueCode.invalid_type:
+        if (issue.received === "undefined") {
+          return { message: t("required") };
+        }
+        break;
+    }
+    return { message: ctx.defaultError };
+  };
+}
+```
+
+## Date and Number Formatting
+
+```tsx
+import { useFormatter } from "next-intl";
+
+function PriceDisplay({ amount }: { amount: number }) {
+  const format = useFormatter();
+  return <span>{format.number(amount, { style: "currency", currency: "EUR" })}</span>;
+}
+
+function DateDisplay({ date }: { date: Date }) {
+  const format = useFormatter();
+  return <span>{format.dateTime(date, { dateStyle: "medium" })}</span>;
+}
+```

package/data/skills/layered-architecture/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: layered-architecture
+description: "Enforces strict layered architecture: Presentation → Facade → Service → DAL → Persistence. Use when structuring a Next.js application, creating new features with separation of concerns, or refactoring code into layers."
+---
+
+# Layered Architecture
+
+Strict separation of concerns across five layers. Each layer only calls the layer directly below it.
+
+## Critical Rules
+
+- **Never skip layers** — presentation must not call services directly.
+- **No business logic in facades** — they coordinate, not decide.
+- **No auth checks in DAL** — DAL is purely data access.
+- **No database calls in services** — services call DAL.
+- **Functional style** — pure functions, no classes, prefer composition over inheritance.
+- **Top-down design** — keep functions short, extract when >100 lines.
+
+## Layer Overview
+
+```
+Presentation (RSC / Client Components)
+    ↓
+Facade (entry point for business logic)
+    ↓
+Service (business rules, authorization)
+    ↓
+DAL — Data Access Layer (queries, data shaping)
+    ↓
+Persistence (Drizzle ORM / database)
+```
+
+## Presentation Layer
+
+- React Server Components and Client Components live here.
+- Components call **facades only** — never services or DAL directly.
+- RSC by default. Only add `"use client"` when strictly needed (hooks, events, browser APIs).
+- Top-down design: if a component exceeds ~100 lines, extract sub-functions/sub-components.
+- Functional over OOP — pure functions, composition, immutability.
+
+```tsx
+// app/(app)/users/page.tsx — Presentation
+import { getUserList } from "@/facades/user.facade";
+
+export default async function UsersPage() {
+  const users = await getUserList();
+  return <UserTable users={users} />;
+}
+```
+
+## Facade Layer
+
+- Entry points for business logic. One facade per domain entity.
+- Located in `src/facades/` — files named `{entity}.facade.ts`.
+- Facades orchestrate service calls and transform data for the presentation.
+- Facades handle auth context extraction and pass it down.
+- Never contain business logic — only coordination.
+
+```ts
+// src/facades/user.facade.ts
+import { getCurrentUser } from "@/lib/auth";
+import { listUsers, createUser } from "@/services/user.service";
+
+export async function getUserList() {
+  const currentUser = await getCurrentUser();
+  return listUsers(currentUser);
+}
+```
+
+## Service Layer
+
+- Contains all business rules and authorization checks.
+- Located in `src/services/` — files named `{entity}.service.ts`.
+- Services receive the auth context as parameter — never fetch it themselves.
+- CASL authorization checks happen here.
+- Services call DAL functions for data access.
+
+```ts
+// src/services/user.service.ts
+import { ForbiddenError } from "@casl/ability";
+import { defineAbilityFor } from "@/lib/casl";
+import { findAllUsers } from "@/dal/user.dal";
+
+export async function listUsers(currentUser: AuthUser) {
+  const ability = defineAbilityFor(currentUser);
+  ForbiddenError.from(ability).throwUnlessCan("read", "User");
+  return findAllUsers();
+}
+```
+
+## Data Access Layer (DAL)
+
+- Pure data access — no business logic, no authorization.
+- Located in `src/dal/` — files named `{entity}.dal.ts`.
+- DAL functions shape data: select specific columns, join relations, paginate.
+- Always return typed results — never raw query results.
+
+```ts
+// src/dal/user.dal.ts
+import { db } from "@/lib/db";
+import { users } from "@/schema";
+
+export async function findAllUsers() {
+  return db.select({
+    id: users.id,
+    name: users.name,
+    email: users.email,
+    role: users.role,
+  }).from(users);
+}
+```
+
+## Persistence Layer
+
+- Drizzle ORM schema definitions and database client.
+- Located in `src/schema/` for table definitions, `src/lib/db.ts` for the client.
+- Schema-only — no query logic here.
+
+## File Naming Convention
+
+```
+src/
+  facades/         # {entity}.facade.ts
+  services/        # {entity}.service.ts
+  dal/             # {entity}.dal.ts
+  schema/          # {entity}.ts (Drizzle table defs)
+  lib/db.ts        # Database client
+```
+
+- All new files use **kebab-case**.
+- One file per entity per layer — avoid catch-all files.

package/data/skills/nextjs-conventions/SKILL.md

@@ -1,11 +1,18 @@
 ---
 name: nextjs-conventions
-description: "Enforces Next.js 15+ / React 19 / TypeScript conventions and best practices. Use when working on any Next.js project to ensure consistent patterns."
-allowed-tools: "Read, Write, Edit, Glob, Grep"
+description: "Next.js 15+ / React 19 / TypeScript conventions for App Router, RSC, route groups, and file naming. Use when creating pages, components, layouts, or structuring a Next.js application."
 ---
 
 # Next.js Conventions
 
+## Critical Rules
+
+- **RSC by default** — only add `"use client"` when strictly needed.
+- **Functional over OOP** — pure functions, composition, immutability. Never class components.
+- **kebab-case for all new files** — `user-profile.tsx`, `format-date.ts`.
+- **Top-down design** — extract sub-functions/sub-components when >100 lines.
+- **Never use `any`** — use `unknown` if the type is truly unknown.
+
 ## App Router
 
 - Use the App Router (`src/app/`) exclusively. Never use the Pages Router.
@@ -13,14 +20,39 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 - Use `loading.tsx` for Suspense boundaries and `error.tsx` for error boundaries.
 - Use `not-found.tsx` for 404 pages at the appropriate route level.
 
+## Route Groups
+
+Organize routes by access level using route groups:
+
+```
+src/app/
+  (public)/        # No auth required — landing, login, register
+    login/
+    register/
+  (auth)/          # Auth required, any role — onboarding
+    onboarding/
+  (app)/           # Auth required, active user — main app
+    dashboard/
+    settings/
+  admin/           # Admin only — user management, app settings
+    users/
+    settings/
+```
+
+- `(public)` routes are accessible without authentication.
+- `(auth)` routes require a session but no specific role.
+- `(app)` routes require an active, verified user.
+- `admin` routes require admin role — not a route group so the URL reflects `/admin/`.
+
 ## Server vs Client Components
 
-- **Default to Server Components**. Only add `"use client"` when you need:
+- **RSC by default**. Only add `"use client"` when strictly needed:
   - Event handlers (`onClick`, `onChange`, etc.)
   - React hooks (`useState`, `useEffect`, `useRef`, etc.)
   - Browser-only APIs (`window`, `localStorage`, etc.)
 - Never import server-only modules in client components.
 - Pass server data to client components via props, not by importing server functions.
+- Wrap async data in `<Suspense>` boundaries for streaming and progressive rendering.
 
 ## Data Fetching
 
@@ -31,10 +63,10 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 
 ## File Naming
 
-- Components: `PascalCase.tsx` (e.g., `UserProfile.tsx`)
-- Utilities: `kebab-case.ts` (e.g., `format-date.ts`)
-- Types: define in `src/types/` with `.ts` extension
-- Server Actions: `src/actions/{entity}.actions.ts`
+- **All new files: `kebab-case`** (e.g., `user-profile.tsx`, `format-date.ts`).
+- Types: define in `src/types/` with `.ts` extension.
+- Server Actions: `src/actions/{entity}.actions.ts`.
+- Schemas: `src/schemas/{entity}.schema.ts`.
 
 ## TypeScript
 
@@ -62,3 +94,10 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 - Use `next/link` for internal navigation. Never use `<a>` for internal links.
 - Use `next/font` for font loading.
 - Lazy load heavy client components with `dynamic()` from `next/dynamic`.
+
+## Code Design
+
+- **Functional over OOP** — pure functions, composition, immutability. Never use class components.
+- **Top-down design** — if a function or component exceeds ~100 lines, extract sub-functions or sub-components.
+- Prefer named exports over default exports (except for page/layout components).
+- Group imports: React/Next.js first, then external libs, then internal modules.

package/data/skills/react-native-patterns/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: react-native-patterns
+description: "React Native and Expo best practices for navigation, styling, performance, and native features. Use when building mobile apps with Expo, implementing React Native navigation, styling with NativeWind, optimizing mobile performance, or adding push notifications."
+---
+
+# React Native & Expo Patterns
+
+## Critical Rules
+
+- **Always try Expo Go first** — only use `npx expo run:ios/android` when custom native modules are required.
+- **Functional components only** — never class components.
+- **Use `expo-image` instead of React Native's `Image`** — better caching and performance.
+- **Use `react-native-safe-area-context`** — never React Native's built-in `SafeAreaView`.
+- **Use `FlashList` instead of `FlatList`** for large lists — significantly better performance.
+- **Never block the JS thread** — target 60fps, offload heavy computation to native.
+
+## Expo Router
+
+- Use file-based routing in the `app/` directory exclusively.
+- Never co-locate components, types, or utilities in the `app/` directory — keep them in `src/`.
+- Always ensure a route matches `/` (may be inside a group route).
+- Use layout routes (`_layout.tsx`) for shared navigation UI (tabs, stacks, drawers).
+- Remove old route files immediately when restructuring navigation.
+- Use kebab-case for file names: `comment-card.tsx`.
+
+## Styling with NativeWind
+
+- Use NativeWind (Tailwind for React Native) as the primary styling method.
+- Use `className` prop like web Tailwind — NativeWind compiles to StyleSheet.
+- Use `cn()` helper for conditional classes.
+- Prefer `useWindowDimensions` over `Dimensions.get()` for responsive layouts.
+- Use flexbox exclusively for layout — avoid absolute positioning except for overlays.
+
+## Components
+
+- Use functional components only — never class components.
+- Use `expo-image` instead of React Native's `Image` — better caching and performance.
+- Use `expo-image` with `source="sf:name"` for SF Symbols icons — not `@expo/vector-icons`.
+- Use `react-native-safe-area-context` — never React Native's built-in `SafeAreaView`.
+- Use `<ScrollView contentInsetAdjustmentBehavior="automatic" />` instead of `<SafeAreaView>` for root scrolling.
+- Use `process.env.EXPO_OS` instead of `Platform.OS`.
+- Use `React.use` instead of `React.useContext`.
+
+## Navigation
+
+- Use Expo Router's typed routes for type-safe navigation.
+- Handle deep linking and universal links from project start.
+- Use native tabs (`NativeTabs`) for iOS tab navigation when possible.
+- Preload frequently accessed screens for faster navigation.
+
+## Performance
+
+- **Profile before optimizing** — measure with React DevTools and Xcode Instruments.
+- Replace `ScrollView` with `FlashList` (not `FlatList`) for large lists.
+- Use React Compiler for automatic memoization when available.
+- Avoid barrel exports — import directly from source files to reduce bundle size.
+- Keep JS thread work minimal — offload to native with Turbo Modules when needed.
+- Target 60fps — never block the JS thread with heavy computation.
+- Use `useDeferredValue` for expensive computations during rendering.
+
+## Animations
+
+- Use `react-native-reanimated` for performant animations on the UI thread.
+- Animate only `transform` and `opacity` — avoid animating layout properties.
+- Use shared values and worklets for gesture-driven animations.
+- Respect `prefers-reduced-motion` accessibility setting.
+
+## Offline & Storage
+
+- Use `@react-native-async-storage/async-storage` or `react-native-mmkv` for local key-value storage.
+- Use `expo-sqlite` for structured offline data.
+- Implement optimistic updates for network operations.
+- Cache critical data locally for offline-first experience.
+
+## Push Notifications
+
+- Use `expo-notifications` for push notification setup.
+- Request permission at a contextual moment — never on first launch.
+- Handle notification responses (tap, dismiss) in the app root.
+- Store push tokens in your backend database, linked to user profiles.
+
+## App Distribution
+
+- Use EAS Build for creating production builds.
+- Use EAS Submit for app store submissions.
+- Configure `app.json` / `app.config.ts` thoroughly: icons, splash, permissions, version.
+- Test on both iOS and Android — never assume platform parity.

package/data/skills/react-query-patterns/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: react-query-patterns
+description: "TanStack React Query for data fetching, caching, mutations, and optimistic updates. Use when managing server state in client components, implementing data fetching hooks, or caching API responses."
+---
+
+# React Query Patterns
+
+## Critical Rules
+
+- **Query keys are structured** — use the factory pattern from `query-keys.ts`.
+- **Custom hooks for reuse** — wrap `useQuery`/`useMutation` in domain hooks.
+- **Invalidate on mutation** — always invalidate related queries after writes.
+- **Optimistic updates for UX** — use for edits and deletes where latency matters.
+- **Prefetch in RSC** — hydrate queries in server components for instant loads.
+- **Never fetch in useEffect** — use React Query instead.
+
+## Setup
+
+```tsx
+// src/providers/query-provider.tsx
+"use client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useState } from "react";
+
+export function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            staleTime: 60 * 1000, // 1 minute
+            refetchOnWindowFocus: false,
+          },
+        },
+      })
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}
+```
+
+## Query Keys Convention
+
+```ts
+// src/lib/query-keys.ts
+export const queryKeys = {
+  users: {
+    all: ["users"] as const,
+    list: (filters: UserFilters) => ["users", "list", filters] as const,
+    detail: (id: string) => ["users", "detail", id] as const,
+  },
+  posts: {
+    all: ["posts"] as const,
+    list: (filters: PostFilters) => ["posts", "list", filters] as const,
+    detail: (id: string) => ["posts", "detail", id] as const,
+    comments: (postId: string) => ["posts", postId, "comments"] as const,
+  },
+} as const;
+```
+
+## Queries
+
+### Basic Query
+
+```tsx
+"use client";
+import { useQuery } from "@tanstack/react-query";
+import { queryKeys } from "@/lib/query-keys";
+
+export function UserList() {
+  const { data: users, isLoading, error } = useQuery({
+    queryKey: queryKeys.users.all,
+    queryFn: () => fetch("/api/users").then((r) => r.json()),
+  });
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} />;
+
+  return <ul>{users.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+### Query with Server Action
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { getUserList } from "@/actions/user.actions";
+
+const { data } = useQuery({
+  queryKey: queryKeys.users.list(filters),
+  queryFn: () => getUserList(filters),
+});
+```
+
+## Mutations
+
+### Basic Mutation
+
+```tsx
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { createUser } from "@/actions/user.actions";
+import { queryKeys } from "@/lib/query-keys";
+import { toast } from "sonner";
+
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createUser,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+      toast.success("User created");
+    },
+    onError: (error) => {
+      toast.error(error.message);
+    },
+  });
+}
+```
+
+### Optimistic Update
+
+```tsx
+export function useUpdateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: UpdateUserInput }) =>
+      updateUser(id, data),
+    onMutate: async ({ id, data }) => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.users.detail(id) });
+      const previous = queryClient.getQueryData(queryKeys.users.detail(id));
+      queryClient.setQueryData(queryKeys.users.detail(id), (old: User) => ({
+        ...old,
+        ...data,
+      }));
+      return { previous };
+    },
+    onError: (_err, { id }, context) => {
+      queryClient.setQueryData(queryKeys.users.detail(id), context?.previous);
+    },
+    onSettled: (_data, _err, { id }) => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.users.detail(id) });
+    },
+  });
+}
+```
+
+## Custom Hooks
+
+```ts
+// src/hooks/use-users.ts
+export function useUsers(filters?: UserFilters) {
+  return useQuery({
+    queryKey: queryKeys.users.list(filters ?? {}),
+    queryFn: () => getUserList(filters),
+  });
+}
+
+export function useUser(id: string) {
+  return useQuery({
+    queryKey: queryKeys.users.detail(id),
+    queryFn: () => getUserById(id),
+    enabled: !!id,
+  });
+}
+```
+
+## Prefetching with RSC
+
+```tsx
+// app/users/page.tsx (Server Component)
+import { HydrationBoundary, dehydrate, QueryClient } from "@tanstack/react-query";
+import { getUserList } from "@/actions/user.actions";
+import { queryKeys } from "@/lib/query-keys";
+import { UserList } from "./user-list";
+
+export default async function UsersPage() {
+  const queryClient = new QueryClient();
+  await queryClient.prefetchQuery({
+    queryKey: queryKeys.users.all,
+    queryFn: getUserList,
+  });
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <UserList />
+    </HydrationBoundary>
+  );
+}
+```