@folpe/loom 0.1.0 → 0.3.0

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

@@ -0,0 +1,110 @@
+---
+name: supabase-patterns
+description: "Supabase patterns for auth, database, RLS, storage, and real-time. Use when working with Supabase, writing RLS policies, implementing auth flows, or managing file storage."
+---
+
+# Supabase Patterns
+
+## Critical Rules
+
+- **Enable RLS on every table — no exceptions**, even internal tables.
+- **Always validate session server-side** — never trust client-side `getUser()` alone.
+- **Use `@supabase/ssr`** — never `@supabase/auth-helpers-nextjs` (deprecated).
+- **Handle errors explicitly** — never ignore the `error` return value.
+- **Use `LIMIT`** on all queries — never fetch unbounded result sets.
+- **RLS policies on storage buckets** — no exceptions.
+
+## Authentication
+
+- Use `@supabase/ssr` for Next.js server-side auth.
+- Create two client helpers:
+  - `createClient()` in `src/lib/supabase/client.ts` for Client Components
+  - `createServerClient()` in `src/lib/supabase/server.ts` for Server Components / Actions
+- Always validate session server-side before granting access.
+- Use middleware (`middleware.ts`) to refresh the session on every request:
+  ```ts
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user && protectedRoutes.includes(request.nextUrl.pathname)) {
+    return NextResponse.redirect(new URL('/login', request.url))
+  }
+  ```
+- Support multiple auth strategies: email/password, OAuth (Google, GitHub), magic link.
+- Store user metadata in a separate `profiles` table linked by `auth.users.id`.
+
+## Row Level Security (RLS)
+
+- Write policies that reference `auth.uid()` directly:
+  ```sql
+  CREATE POLICY "Users read own data"
+    ON profiles FOR SELECT
+    USING (auth.uid() = user_id);
+  ```
+- Avoid `security definer` functions unless absolutely necessary. Prefer RLS policies.
+- Test policies explicitly: try accessing data as different users/roles.
+- Use `auth.jwt() ->> 'role'` for role-based access if implementing RBAC.
+
+## Database Schema
+
+- Use `uuid` for primary keys, generated by `gen_random_uuid()`.
+- Add `created_at` and `updated_at` timestamps to every table:
+  ```sql
+  created_at timestamptz DEFAULT now() NOT NULL,
+  updated_at timestamptz DEFAULT now() NOT NULL
+  ```
+- Create an `updated_at` trigger using `moddatetime` extension.
+- Use foreign key constraints for referential integrity.
+- Add indexes on columns used in WHERE clauses and JOIN conditions.
+
+## Query Patterns
+
+- Use the Supabase client query builder for simple CRUD:
+  ```ts
+  const { data, error } = await supabase
+    .from('posts')
+    .select('*, author:profiles(name, avatar_url)')
+    .eq('published', true)
+    .order('created_at', { ascending: false })
+    .limit(20)
+  ```
+- Handle errors explicitly — never ignore `error`:
+  ```ts
+  if (error) throw new Error(error.message)
+  ```
+- Use `.single()` when expecting exactly one row. Use `.maybeSingle()` when the row may not exist.
+- Use server-side Supabase client for mutations in Server Actions.
+
+## Real-time
+
+- Use Supabase Realtime only for features that genuinely need live updates (chat, notifications, collaboration).
+- Subscribe in Client Components and clean up on unmount:
+  ```ts
+  useEffect(() => {
+    const channel = supabase.channel('room').on('postgres_changes', { event: '*', schema: 'public', table: 'messages' }, handler).subscribe()
+    return () => { supabase.removeChannel(channel) }
+  }, [])
+  ```
+- Prefer polling or revalidation for data that changes infrequently.
+
+## Storage
+
+- Use Supabase Storage for file uploads (images, documents).
+- Create separate buckets for public vs private files.
+- Set RLS policies on storage buckets — **no exceptions**.
+- Generate signed URLs for private files with short expiration times.
+- File upload pattern:
+  ```ts
+  const { data, error } = await supabase.storage
+    .from("avatars")
+    .upload(`${userId}/${fileName}`, file, {
+      cacheControl: "3600",
+      upsert: true,
+    });
+  ```
+- Get public URL: `supabase.storage.from("avatars").getPublicUrl(path)`.
+
+## Performance
+
+- Use connection pooling (Supavisor) in production — never connect directly at scale.
+- Add `LIMIT` to all queries. Never fetch unbounded result sets.
+- Use `select('column1, column2')` instead of `select('*')` for large tables.
+- Create partial indexes for frequently filtered subsets of data.

package/data/skills/table-pagination/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: table-pagination
+description: "Data table patterns with server-side pagination, toolbar, and responsive columns. Use when building data tables, implementing search and pagination, or creating admin list views."
+---
+
+# Table & Pagination Patterns
+
+## Critical Rules
+
+- **Server-side pagination** — paginate in the database, not in the client.
+- **URL-based state** — page, limit, search, sort in query params for shareable URLs.
+- **Toolbar = search + counter + limit** — consistent UX across all tables.
+- **Responsive columns** — hide columns with `hidden sm:table-cell` breakpoints.
+- **Reset page on filter change** — always return to page 1 when search/filter changes.
+- **Use `tabular-nums`** on numeric columns — for proper alignment.
+
+## Table Architecture
+
+```
+DataTable (container)
+  ├── Toolbar (search + filters + counter + limit selector)
+  ├── Table (columns + rows)
+  └── Pagination (page navigation)
+```
+
+## Server-Side Pagination
+
+### URL-Based State
+
+```tsx
+// app/users/page.tsx
+import { Suspense } from "react";
+import { getUsersPaginated } from "@/facades/user.facade";
+
+interface Props {
+  searchParams: Promise<{
+    page?: string;
+    limit?: string;
+    search?: string;
+    sort?: string;
+    order?: string;
+  }>;
+}
+
+export default async function UsersPage({ searchParams }: Props) {
+  const params = await searchParams;
+  const page = Number(params.page) || 1;
+  const limit = Number(params.limit) || 20;
+
+  const { data, total } = await getUsersPaginated({
+    page,
+    limit,
+    search: params.search,
+    sort: params.sort,
+    order: params.order as "asc" | "desc",
+  });
+
+  return (
+    <DataTable
+      columns={columns}
+      data={data}
+      total={total}
+      page={page}
+      limit={limit}
+    />
+  );
+}
+```
+
+### Backend Pagination
+
+```ts
+// src/dal/user.dal.ts
+import { db } from "@/lib/db";
+import { users } from "@/schema";
+import { sql, ilike, desc, asc } from "drizzle-orm";
+
+interface PaginationParams {
+  page: number;
+  limit: number;
+  search?: string;
+  sort?: string;
+  order?: "asc" | "desc";
+}
+
+export async function findUsersPaginated(params: PaginationParams) {
+  const { page, limit, search, sort = "createdAt", order = "desc" } = params;
+  const offset = (page - 1) * limit;
+
+  const where = search ? ilike(users.name, `%${search}%`) : undefined;
+  const orderBy = order === "asc" ? asc(users[sort]) : desc(users[sort]);
+
+  const [data, [{ count }]] = await Promise.all([
+    db.select().from(users).where(where).orderBy(orderBy).limit(limit).offset(offset),
+    db.select({ count: sql<number>`count(*)` }).from(users).where(where),
+  ]);
+
+  return { data, total: Number(count) };
+}
+```
+
+## Table Toolbar
+
+```tsx
+"use client";
+
+export function DataTableToolbar({ table, total }: ToolbarProps) {
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  const pathname = usePathname();
+
+  function updateParam(key: string, value: string) {
+    const params = new URLSearchParams(searchParams);
+    if (value) params.set(key, value);
+    else params.delete(key);
+    params.delete("page"); // reset to page 1 on filter change
+    router.push(`${pathname}?${params}`);
+  }
+
+  return (
+    <div className="flex items-center justify-between gap-2">
+      <div className="flex flex-1 items-center gap-2">
+        <Input
+          placeholder="Search..."
+          defaultValue={searchParams.get("search") ?? ""}
+          onChange={(e) => updateParam("search", e.target.value)}
+          className="h-8 w-[250px]"
+        />
+        <span className="text-sm text-muted-foreground">
+          {total} result{total !== 1 ? "s" : ""}
+        </span>
+      </div>
+      <div className="flex items-center gap-2">
+        <Select
+          defaultValue={searchParams.get("limit") ?? "20"}
+          onValueChange={(v) => updateParam("limit", v)}
+        >
+          <SelectTrigger className="h-8 w-[80px]">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {[10, 20, 50, 100].map((n) => (
+              <SelectItem key={n} value={String(n)}>{n}</SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+    </div>
+  );
+}
+```
+
+## Responsive Columns
+
+Hide columns by breakpoint to keep tables readable on mobile:
+
+```tsx
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: "name",
+    header: "Name",
+    // Always visible
+  },
+  {
+    accessorKey: "email",
+    header: "Email",
+    meta: { className: "hidden sm:table-cell" },
+  },
+  {
+    accessorKey: "role",
+    header: "Role",
+    meta: { className: "hidden md:table-cell" },
+  },
+  {
+    accessorKey: "createdAt",
+    header: "Created",
+    meta: { className: "hidden lg:table-cell" },
+    cell: ({ row }) => formatDate(row.getValue("createdAt")),
+  },
+];
+```
+
+Apply the responsive class in the table cell:
+
+```tsx
+<TableCell className={column.columnDef.meta?.className}>
+  {flexRender(cell.column.columnDef.cell, cell.getContext())}
+</TableCell>
+```
+
+## Pagination Component
+
+```tsx
+"use client";
+
+export function DataTablePagination({ page, limit, total }: PaginationProps) {
+  const totalPages = Math.ceil(total / limit);
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  const pathname = usePathname();
+
+  function goToPage(p: number) {
+    const params = new URLSearchParams(searchParams);
+    params.set("page", String(p));
+    router.push(`${pathname}?${params}`);
+  }
+
+  return (
+    <div className="flex items-center justify-between px-2">
+      <p className="text-sm text-muted-foreground">
+        Page {page} of {totalPages}
+      </p>
+      <div className="flex items-center gap-2">
+        <Button variant="outline" size="sm" onClick={() => goToPage(page - 1)} disabled={page <= 1}>
+          Previous
+        </Button>
+        <Button variant="outline" size="sm" onClick={() => goToPage(page + 1)} disabled={page >= totalPages}>
+          Next
+        </Button>
+      </div>
+    </div>
+  );
+}
+```

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

@@ -1,11 +1,18 @@
 ---
 name: tailwind-patterns
-description: "Provides Tailwind CSS patterns, utility conventions, and component styling guidelines. Use when building UI with Tailwind CSS."
-allowed-tools: "Read, Write, Edit"
+description: "Tailwind CSS utility conventions, responsive design, and component styling. Use when styling components, implementing responsive layouts, or applying consistent spacing and typography."
 ---
 
 # Tailwind CSS Patterns
 
+## Critical Rules
+
+- **Utility-first** — use utility classes directly in JSX, avoid `@apply`.
+- **Mobile-first** — base styles for mobile, then `sm:`, `md:`, `lg:`, `xl:`.
+- **Semantic color tokens** — use `bg-background`, `text-foreground`, never hardcode hex.
+- **Progressive padding** — `px-0 sm:px-2 md:px-4 lg:px-6` grows with viewport.
+- **Use `cn()`** — from `@/lib/utils` for conditional and merged classes.
+
 ## Utility-First Approach
 
 - Always use utility classes directly in JSX. Avoid `@apply` except in global base styles.
@@ -30,6 +37,9 @@ allowed-tools: "Read, Write, Edit"
   - `lg:` (1024px) — laptops
   - `xl:` (1280px) — desktops
 - Grid responsive pattern: `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3`
+- **Progressive padding**: `px-0 sm:px-2 md:px-4 lg:px-6` — spacing grows with viewport.
+- **Cards border adaptatif**: `border-0 sm:border` — no border on mobile, border on larger screens.
+- **Table columns by breakpoint**: hide non-essential columns on small screens with `hidden sm:table-cell`, `hidden md:table-cell`, `hidden lg:table-cell`.
 
 ## Typography
 

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

@@ -0,0 +1,203 @@
+---
+name: testing-patterns
+description: "Vitest testing strategy with role-based patterns, seed data factories, and CI/CD integration. Use when writing tests, creating test data, or setting up continuous integration pipelines."
+---
+
+# Testing Patterns
+
+## Critical Rules
+
+- **Test every role** — PUBLIC, USER, ADMIN for every feature.
+- **Test services, not routes** — service layer is the source of truth.
+- **Use seed factories** — deterministic, reusable test data.
+- **Clean up after each test** — truncate tables, no test pollution.
+- **CI runs tests + build** — every PR must pass before merge.
+- **No mocking the database** — test against a real PostgreSQL instance.
+
+## Role-Based Test Matrix
+
+Every feature must be tested from 3 perspectives:
+
+| Role | What to test |
+|------|-------------|
+| **PUBLIC** | Unauthenticated access — redirects, public pages, API 401s |
+| **USER** | Standard user — CRUD own resources, forbidden on others |
+| **ADMIN** | Admin user — manage all resources, admin-only features |
+
+```ts
+describe("deletePost", () => {
+  it("should return 401 for public (unauthenticated)", async () => {
+    const result = await deletePost(null, postId);
+    expect(result.error).toBe("Unauthorized");
+  });
+
+  it("should allow USER to delete own post", async () => {
+    const result = await deletePost(userSession, ownPostId);
+    expect(result.success).toBe(true);
+  });
+
+  it("should forbid USER from deleting another's post", async () => {
+    const result = await deletePost(userSession, otherPostId);
+    expect(result.error).toBe("Forbidden");
+  });
+
+  it("should allow ADMIN to delete any post", async () => {
+    const result = await deletePost(adminSession, otherPostId);
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+## Vitest Configuration
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import path from "path";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    setupFiles: ["./tests/setup.ts"],
+    include: ["**/*.test.ts", "**/*.test.tsx"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "lcov"],
+      exclude: ["node_modules", "tests/setup.ts"],
+    },
+  },
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+});
+```
+
+## Seed Data
+
+### Seed Users
+
+```ts
+// tests/seed/users.ts
+export const SEED_USERS = {
+  public: null, // no session
+  user: {
+    id: "user-1",
+    email: "user@test.com",
+    name: "Test User",
+    role: "USER" as const,
+  },
+  admin: {
+    id: "admin-1",
+    email: "admin@test.com",
+    name: "Test Admin",
+    role: "ADMIN" as const,
+  },
+} as const;
+```
+
+### Seed Data Factory
+
+```ts
+// tests/seed/factories.ts
+import { db } from "@/lib/db";
+import { users, posts } from "@/schema";
+
+export async function seedUser(overrides?: Partial<NewUser>) {
+  const [user] = await db.insert(users).values({
+    name: "Test User",
+    email: `test-${Date.now()}@test.com`,
+    role: "USER",
+    ...overrides,
+  }).returning();
+  return user;
+}
+
+export async function seedPost(authorId: string, overrides?: Partial<NewPost>) {
+  const [post] = await db.insert(posts).values({
+    title: "Test Post",
+    content: "Test content",
+    authorId,
+    published: true,
+    ...overrides,
+  }).returning();
+  return post;
+}
+```
+
+## Test Setup
+
+```ts
+// tests/setup.ts
+import { beforeAll, afterAll, afterEach } from "vitest";
+import { db } from "@/lib/db";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+
+beforeAll(async () => {
+  await migrate(db, { migrationsFolder: "./drizzle" });
+});
+
+afterEach(async () => {
+  // Clean up test data — truncate in reverse FK order
+  await db.execute(sql`TRUNCATE posts, users CASCADE`);
+});
+```
+
+## Service Layer Testing
+
+```ts
+// src/services/__tests__/user.service.test.ts
+import { describe, it, expect, beforeEach } from "vitest";
+import { listUsers, deleteUser } from "@/services/user.service";
+import { SEED_USERS } from "tests/seed/users";
+import { seedUser } from "tests/seed/factories";
+
+describe("user.service", () => {
+  let testUser: User;
+
+  beforeEach(async () => {
+    testUser = await seedUser();
+  });
+
+  describe("listUsers", () => {
+    it("should allow ADMIN to list all users", async () => {
+      const result = await listUsers(SEED_USERS.admin);
+      expect(result).toHaveLength(1);
+    });
+
+    it("should forbid USER from listing users", async () => {
+      await expect(listUsers(SEED_USERS.user)).rejects.toThrow("Forbidden");
+    });
+  });
+});
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: test
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+        ports: ["5432:5432"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: "pnpm" }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test
+      - run: pnpm build
+```