@folpe/loom 0.2.0 → 0.3.0

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

@@ -1,18 +1,26 @@
 ---
 name: supabase-patterns
-description: "Supabase best practices for auth, database, RLS, and real-time. Use when working with Supabase in any project. Inspired by supabase/agent-skills."
-allowed-tools: "Read, Write, Edit, Glob, Grep"
+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 — never use `@supabase/auth-helpers-nextjs` (deprecated).
+- 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. Never trust `supabase.auth.getUser()` from the client alone.
+- 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()
@@ -25,7 +33,6 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 
 ## Row Level Security (RLS)
 
-- **Enable RLS on every table** — no exceptions, even internal tables.
 - Write policies that reference `auth.uid()` directly:
   ```sql
   CREATE POLICY "Users read own data"
@@ -82,8 +89,18 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 
 - Use Supabase Storage for file uploads (images, documents).
 - Create separate buckets for public vs private files.
-- Set RLS policies on storage buckets.
+- 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
 

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
+```

package/data/skills/ui-ux-guidelines/SKILL.md

@@ -1,19 +1,25 @@
 ---
 name: ui-ux-guidelines
-description: "Comprehensive UI/UX design intelligence: accessibility, interaction patterns, typography, color palettes, animation rules, and pre-delivery checklist. Use when building any user-facing interface. Inspired by nextlevelbuilder/ui-ux-pro-max-skill."
-allowed-tools: "Read, Write, Edit, Glob, Grep"
+description: "UI/UX design rules for accessibility, interaction, typography, color, and animation. Use when building user-facing interfaces, reviewing designs, checking accessibility compliance, or choosing fonts and color palettes."
 ---
 
 # UI/UX Design Guidelines
 
 Comprehensive design guide covering accessibility, interaction, layout, typography, color, and animation — prioritized by impact.
 
+## Critical Rules
+
+- **Color contrast**: minimum 4.5:1 for normal text, 3:1 for large text.
+- **Touch targets**: minimum 44x44px on mobile.
+- **No `h-screen`** — use `h-dvh` for correct mobile viewport.
+- **No animation unless requested** — respect `prefers-reduced-motion`.
+- **Empty states must have one clear next action** — never blank screens.
+- **All icon-only buttons must have `aria-label`**.
+
 ## Priority 1 — Accessibility (CRITICAL)
 
-- **Color contrast**: minimum 4.5:1 ratio for normal text, 3:1 for large text.
 - **Color is not enough**: never convey information by color alone — add icons or text.
 - **Alt text**: descriptive alt for all meaningful images. Use `alt=""` only for decorative images.
-- **ARIA labels**: every icon-only button must have `aria-label`.
 - **Heading hierarchy**: sequential h1 → h2 → h3, one `<h1>` per page.
 - **Keyboard navigation**: tab order matches visual order, no keyboard traps.
 - **Focus states**: visible focus rings on all interactive elements — never `outline-none` without replacement.
@@ -24,7 +30,6 @@ Comprehensive design guide covering accessibility, interaction, layout, typograp
 
 ## Priority 2 — Touch & Interaction (CRITICAL)
 
-- **Touch targets**: minimum 44x44px on mobile — `min-h-[44px] min-w-[44px]`.
 - **Touch spacing**: minimum 8px gap between adjacent touch targets.
 - **Hover vs tap**: never rely on hover for primary interactions — use click/tap.
 - **Cursor pointer**: add `cursor-pointer` to all clickable elements.