@folpe/loom 0.1.0 → 0.3.0

package/data/skills/api-design/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: api-design
+description: "REST API design with validation, error handling, auth wrappers, and facades. Use when building API routes, server actions, implementing auth middleware, or designing backend services."
+---
+
+# API Design Principles
+
+## Critical Rules
+
+- **Validate all incoming data** with Zod schemas at the API boundary.
+- **Never expose stack traces** or internal details in production error responses.
+- **Always use facades** between presentation and services.
+- **Auth wrappers on every protected endpoint** — `withAuth()`, `withAdmin()`.
+- **Consistent response shapes** — `{ data }` for success, `{ error, code }` for errors.
+- **Parameterized queries only** — never string concatenation for SQL.
+
+## Route Structure
+
+- Use resource-based URLs: `/api/users`, `/api/posts/:id/comments`.
+- Use HTTP methods semantically:
+  - `GET` — read (no side effects)
+  - `POST` — create
+  - `PUT/PATCH` — update (PUT replaces, PATCH partial update)
+  - `DELETE` — remove
+- Nest sub-resources only one level deep: `/api/posts/:id/comments` — not deeper.
+- Use plural nouns for collections: `/api/users` (not `/api/user`).
+
+## Request Validation
+
+- Validate **all** incoming data with Zod schemas at the API boundary:
+  ```ts
+  const CreatePostSchema = z.object({
+    title: z.string().min(1).max(200),
+    content: z.string().min(1),
+    published: z.boolean().default(false),
+  })
+
+  const body = CreatePostSchema.parse(await request.json())
+  ```
+- Return 400 with structured validation errors:
+  ```json
+  { "error": "Validation failed", "details": [{ "field": "title", "message": "Required" }] }
+  ```
+- Validate path params, query params, and headers — not just body.
+
+## Response Format
+
+- Use consistent response shapes across all endpoints:
+  ```ts
+  // Success
+  { "data": { ... } }
+  { "data": [...], "pagination": { "total": 100, "page": 1, "pageSize": 20 } }
+
+  // Error
+  { "error": "Not found", "code": "RESOURCE_NOT_FOUND" }
+  ```
+- Always return appropriate HTTP status codes:
+  - `200` — success
+  - `201` — created
+  - `204` — no content (successful delete)
+  - `400` — bad request (validation error)
+  - `401` — unauthorized (no/invalid auth)
+  - `403` — forbidden (insufficient permissions)
+  - `404` — not found
+  - `409` — conflict (duplicate resource)
+  - `429` — too many requests (rate limit)
+  - `500` — internal server error
+
+## Error Handling
+
+- Catch errors at the route handler level with a consistent pattern:
+  ```ts
+  try {
+    // ... handler logic
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: 'Validation failed', details: error.errors }, { status: 400 })
+    }
+    console.error('Unhandled error:', error)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+  ```
+- Never expose stack traces or internal details in production error responses.
+- Log errors server-side with request context (method, path, user ID).
+
+## Authentication & Authorization
+
+- Validate auth on every protected endpoint — middleware + route-level checks.
+- Extract user from session/token, never from request body.
+- Check permissions at the resource level: "Can this user access THIS specific post?"
+- Return `401` for missing/invalid auth, `403` for insufficient permissions.
+
+### Auth Wrappers
+
+Use auth wrapper functions for consistent protection:
+
+```ts
+// Require any authenticated user
+export async function withAuth() {
+  const user = await getCurrentUser();
+  if (!user) throw new ApiError(401, "Unauthorized");
+  return user;
+}
+
+// Require authenticated user with valid token
+export async function withAuthToken(request: Request) {
+  const token = request.headers.get("authorization")?.replace("Bearer ", "");
+  if (!token) throw new ApiError(401, "Missing token");
+  return verifyToken(token);
+}
+
+// Dynamic auth — optional session, different behavior for authed/unauthed
+export async function withDynamicAuth() {
+  const user = await getCurrentUser();
+  return { user, isAuthenticated: !!user };
+}
+```
+
+## Facades
+
+- **Always use facades** between presentation and services.
+- One facade per domain entity in `src/facades/`.
+- Facades handle auth context extraction and coordinate service calls.
+- Routes/pages call facades — never services directly.
+
+## Rate Limiting
+
+- Implement rate limiting on public endpoints and auth endpoints.
+- Use token bucket or sliding window algorithm.
+- Return `429` with `Retry-After` header when rate limited.
+- Rate limit by IP for public endpoints, by user ID for authenticated endpoints.
+
+## Pagination
+
+- Use cursor-based pagination for large datasets:
+  ```
+  GET /api/posts?cursor=abc123&limit=20
+  ```
+- Return pagination metadata: `{ "data": [...], "nextCursor": "def456", "hasMore": true }`
+- Default limit to 20, max to 100.
+- For simple cases, offset-based is acceptable: `?page=1&pageSize=20`.
+
+## Security
+
+- Validate Content-Type header on POST/PUT/PATCH requests.
+- Set CORS headers explicitly — never use `*` in production.
+- Sanitize user input before database queries.
+- Use parameterized queries — never string concatenation for SQL.
+- Set security headers: `X-Content-Type-Options`, `X-Frame-Options`, `Strict-Transport-Security`.

package/data/skills/auth-rbac/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: auth-rbac
+description: "CASL-based authorization with role hierarchies, organization roles, and safe route protection. Use when implementing access control, role-based permissions, or protecting routes and API endpoints."
+---
+
+# Auth & RBAC Patterns
+
+## Critical Rules
+
+- **Authorization in services, not routes** — use CASL in the service layer.
+- **Route groups for access control** — `(public)`, `(auth)`, `(app)`, `admin`.
+- **Middleware for redirects** — protect routes at the edge.
+- **Auth wrappers for pages** — `withAuth()`, `withAdmin()` in server components.
+- **Never trust client-side role checks** — always verify server-side.
+- **Principle of least privilege** — grant minimum required permissions.
+
+## Role System
+
+### Application Roles
+
+```ts
+// src/lib/roles.ts
+export const APP_ROLES = ["USER", "ADMIN", "SUPER_ADMIN"] as const;
+export type AppRole = (typeof APP_ROLES)[number];
+```
+
+### Organization Roles
+
+```ts
+export const ORG_ROLES = ["MEMBER", "MANAGER", "OWNER"] as const;
+export type OrgRole = (typeof ORG_ROLES)[number];
+```
+
+- Every user has an **app role** (global) and an **org role** (per organization).
+- Role checks always consider both: app role for platform features, org role for org resources.
+
+## CASL Authorization
+
+### Ability Definition
+
+```ts
+// src/lib/casl.ts
+import { AbilityBuilder, createMongoAbility, type MongoAbility } from "@casl/ability";
+
+type Actions = "create" | "read" | "update" | "delete" | "manage";
+type Subjects = "User" | "Post" | "Organization" | "all";
+export type AppAbility = MongoAbility<[Actions, Subjects]>;
+
+export function defineAbilityFor(user: AuthUser): AppAbility {
+  const { can, cannot, build } = new AbilityBuilder<AppAbility>(createMongoAbility);
+
+  // Base permissions for all authenticated users
+  can("read", "Post", { published: true });
+  can("update", "User", { id: user.id }); // own profile
+
+  if (user.role === "ADMIN") {
+    can("manage", "User");
+    can("manage", "Post");
+    can("read", "Organization");
+  }
+
+  if (user.role === "SUPER_ADMIN") {
+    can("manage", "all");
+  }
+
+  return build();
+}
+```
+
+### Organization Ability
+
+```ts
+export function defineOrgAbilityFor(user: AuthUser, orgRole: OrgRole): AppAbility {
+  const { can, build } = new AbilityBuilder<AppAbility>(createMongoAbility);
+
+  can("read", "Organization");
+
+  if (orgRole === "MANAGER" || orgRole === "OWNER") {
+    can("update", "Organization");
+    can("manage", "User"); // manage org members
+  }
+
+  if (orgRole === "OWNER") {
+    can("delete", "Organization");
+  }
+
+  return build();
+}
+```
+
+## Service Layer Authorization
+
+Check permissions in the **service layer**, never in presentation or DAL:
+
+```ts
+// src/services/post.service.ts
+import { ForbiddenError } from "@casl/ability";
+import { defineAbilityFor } from "@/lib/casl";
+
+export async function deletePost(user: AuthUser, postId: string) {
+  const ability = defineAbilityFor(user);
+  const post = await findPostById(postId);
+
+  ForbiddenError.from(ability).throwUnlessCan("delete", {
+    ...post,
+    __typename: "Post",
+  });
+
+  return removePost(postId);
+}
+```
+
+## Safe Route Protection
+
+### Middleware-Level
+
+```ts
+// middleware.ts
+const publicRoutes = ["/", "/login", "/register", "/api/webhook"];
+const adminRoutes = ["/admin"];
+
+export async function middleware(request: NextRequest) {
+  const session = await getSession();
+
+  if (!session && !publicRoutes.some(r => request.nextUrl.pathname.startsWith(r))) {
+    return NextResponse.redirect(new URL("/login", request.url));
+  }
+
+  if (adminRoutes.some(r => request.nextUrl.pathname.startsWith(r))) {
+    if (session?.user.role !== "ADMIN" && session?.user.role !== "SUPER_ADMIN") {
+      return NextResponse.redirect(new URL("/", request.url));
+    }
+  }
+}
+```
+
+### Route Group Structure
+
+```
+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/
+```
+
+### Auth Wrappers
+
+```ts
+// src/lib/auth-wrappers.ts
+import { getCurrentUser } from "@/lib/auth";
+import { redirect } from "next/navigation";
+
+export async function withAuth() {
+  const user = await getCurrentUser();
+  if (!user) redirect("/login");
+  return user;
+}
+
+export async function withAdmin() {
+  const user = await withAuth();
+  if (user.role !== "ADMIN" && user.role !== "SUPER_ADMIN") redirect("/");
+  return user;
+}
+
+export async function withOrgRole(orgId: string, requiredRole: OrgRole) {
+  const user = await withAuth();
+  const membership = await getOrgMembership(user.id, orgId);
+  if (!membership || !hasOrgRole(membership.role, requiredRole)) redirect("/");
+  return { user, membership };
+}
+```

package/data/skills/better-auth-patterns/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: better-auth-patterns
+description: "Better Auth setup with session management, social login, organization plugin, and middleware. Use when implementing authentication, adding social login providers, or managing user sessions with Better Auth."
+---
+
+# Better Auth Patterns
+
+## Critical Rules
+
+- **Server-side session check** — use `getCurrentUser()` in RSC and Server Actions.
+- **Client-side `useSession()`** — only in Client Components for UI state.
+- **Middleware for redirects** — protect routes at the edge, not in pages.
+- **Never expose auth secrets** — keep `BETTER_AUTH_SECRET` server-only.
+- **Use plugins** — `organization()`, `admin()` for built-in features.
+- **Social login always available** — Google + GitHub as defaults.
+
+## Server Setup
+
+```ts
+// src/lib/auth.ts
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { organization, admin } from "better-auth/plugins";
+import { db } from "@/lib/db";
+
+export const auth = betterAuth({
+  database: drizzleAdapter(db, { provider: "pg" }),
+  emailAndPassword: { enabled: true },
+  socialProviders: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    },
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    },
+  },
+  plugins: [
+    organization(),
+    admin(),
+  ],
+  session: {
+    expiresIn: 60 * 60 * 24 * 7, // 7 days
+    updateAge: 60 * 60 * 24, // refresh daily
+  },
+});
+```
+
+## Client Setup
+
+```ts
+// src/lib/auth-client.ts
+import { createAuthClient } from "better-auth/react";
+import { organizationClient, adminClient } from "better-auth/client/plugins";
+
+export const authClient = createAuthClient({
+  plugins: [organizationClient(), adminClient()],
+});
+
+export const { useSession, signIn, signUp, signOut } = authClient;
+```
+
+## API Route Handler
+
+```ts
+// src/app/api/auth/[...all]/route.ts
+import { auth } from "@/lib/auth";
+import { toNextJsHandler } from "better-auth/next-js";
+
+export const { GET, POST } = toNextJsHandler(auth);
+```
+
+## Session Management
+
+### Server-Side Session
+
+```ts
+// src/lib/auth-server.ts
+import { auth } from "@/lib/auth";
+import { headers } from "next/headers";
+
+export async function getCurrentUser() {
+  const session = await auth.api.getSession({
+    headers: await headers(),
+  });
+  return session?.user ?? null;
+}
+
+export async function requireAuth() {
+  const user = await getCurrentUser();
+  if (!user) redirect("/login");
+  return user;
+}
+```
+
+### Client-Side Session
+
+```tsx
+"use client";
+import { useSession } from "@/lib/auth-client";
+
+export function UserMenu() {
+  const { data: session, isPending } = useSession();
+
+  if (isPending) return <Skeleton />;
+  if (!session) return <LoginButton />;
+
+  return <span>{session.user.name}</span>;
+}
+```
+
+## Authentication Flows
+
+### Sign Up
+
+```tsx
+"use client";
+import { authClient } from "@/lib/auth-client";
+
+async function handleSignUp(data: SignUpInput) {
+  const { error } = await authClient.signUp.email({
+    email: data.email,
+    password: data.password,
+    name: data.name,
+  });
+  if (error) toast.error(error.message);
+  else router.push("/dashboard");
+}
+```
+
+### Social Login
+
+```tsx
+async function handleGoogleLogin() {
+  await authClient.signIn.social({ provider: "google" });
+}
+```
+
+### Sign Out
+
+```tsx
+async function handleSignOut() {
+  await authClient.signOut();
+  router.push("/");
+}
+```
+
+## Middleware
+
+```ts
+// middleware.ts
+import { betterFetch } from "@better-fetch/fetch";
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+import type { Session } from "better-auth/types";
+
+const publicRoutes = ["/", "/login", "/register", "/api/auth"];
+
+export async function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // Skip public routes
+  if (publicRoutes.some((r) => pathname.startsWith(r))) {
+    return NextResponse.next();
+  }
+
+  // Check session
+  const { data: session } = await betterFetch<Session>(
+    "/api/auth/get-session",
+    {
+      baseURL: request.nextUrl.origin,
+      headers: { cookie: request.headers.get("cookie") ?? "" },
+    }
+  );
+
+  if (!session) {
+    return NextResponse.redirect(new URL("/login", request.url));
+  }
+
+  // Admin route protection
+  if (pathname.startsWith("/admin") && session.user.role !== "admin") {
+    return NextResponse.redirect(new URL("/", request.url));
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+## Organization Plugin
+
+```tsx
+// Create organization
+const { data: org } = await authClient.organization.create({
+  name: "Acme Inc",
+  slug: "acme",
+});
+
+// Invite member
+await authClient.organization.inviteMember({
+  email: "user@example.com",
+  role: "member",
+  organizationId: org.id,
+});
+
+// Switch active organization
+await authClient.organization.setActive({ organizationId: org.id });
+```

package/data/skills/chrome-extension-patterns/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: chrome-extension-patterns
+description: "Chrome extension development patterns for Manifest V3, content scripts, popup UI, service workers, messaging, and storage. Use when building browser extensions, creating content scripts, setting up background service workers, or implementing extension popup interfaces."
+---
+
+# Chrome Extension Patterns (Manifest V3)
+
+## Critical Rules
+
+- **Always use Manifest V3** — Manifest V2 is deprecated and no longer accepted.
+- **Minimal permissions** — request only what the extension needs; use `activeTab` over `<all_urls>`.
+- **Never use `setInterval` in service workers** — use `chrome.alarms` for periodic tasks.
+- **Never use `innerHTML` with user input** — use `textContent` to prevent XSS.
+- **Never include API keys in content scripts** — they are visible to the host page.
+- **Never use `localStorage` in content scripts** — it belongs to the host page; use `chrome.storage`.
+
+## Manifest
+
+- Define minimal permissions — request only what the extension needs:
+  ```json
+  {
+    "manifest_version": 3,
+    "permissions": ["storage", "activeTab"],
+    "host_permissions": ["https://specific-site.com/*"]
+  }
+  ```
+- Use `activeTab` instead of broad `<all_urls>` when possible.
+- Declare content scripts and their match patterns explicitly.
+- Use `"action"` (not `"browser_action"`) for the extension button.
+
+## Architecture
+
+- **Popup** (`popup.html/tsx`): lightweight UI shown on extension icon click. Keep it fast — no heavy initialization.
+- **Options page** (`options.html/tsx`): settings and configuration UI.
+- **Background service worker** (`background.ts`): event-driven logic, API calls, alarms, message routing.
+- **Content scripts** (`content.ts`): code injected into web pages to read/modify DOM.
+- Keep these four concerns strictly separated — never mix responsibilities.
+
+## Service Workers (Background)
+
+- Service workers are **event-driven and ephemeral** — they start on events and stop when idle.
+- Never rely on global state persisting between activations. Use `chrome.storage` instead.
+- Register event listeners at the top level (not inside async callbacks):
+  ```ts
+  chrome.runtime.onInstalled.addListener(() => { /* ... */ })
+  chrome.runtime.onMessage.addListener((message, sender, sendResponse) => { /* ... */ })
+  ```
+- Use `chrome.alarms` for periodic tasks — never `setInterval`.
+- Return `true` from `onMessage` listener to send async responses.
+
+## Content Scripts
+
+- Content scripts run in an **isolated world** — they can access the page DOM but not the page's JS variables.
+- Sanitize all DOM manipulation to prevent XSS:
+  ```ts
+  element.textContent = userInput // Safe
+  element.innerHTML = userInput   // DANGEROUS — never do this
+  ```
+- Minimize content script footprint — inject only what's necessary.
+- Use `MutationObserver` for dynamic pages instead of polling.
+- Communicate with background via `chrome.runtime.sendMessage()`.
+
+## Storage
+
+- Use `chrome.storage.local` for large data (up to 10MB).
+- Use `chrome.storage.sync` for user settings that should sync across devices (100KB limit).
+- Never use `localStorage` in content scripts — it belongs to the host page.
+- Listen for storage changes:
+  ```ts
+  chrome.storage.onChanged.addListener((changes, area) => { /* ... */ })
+  ```
+
+## Messaging
+
+- Use `chrome.runtime.sendMessage` for popup/options <-> background communication.
+- Use `chrome.tabs.sendMessage` for background -> content script communication.
+- Define a message type system for type-safe messaging:
+  ```ts
+  type Message =
+    | { type: 'GET_DATA'; payload: { key: string } }
+    | { type: 'SAVE_DATA'; payload: { key: string; value: unknown } }
+  ```
+- Validate all incoming messages — never trust message content blindly.
+
+## Popup UI (React)
+
+- Keep popup bundle small — lazy load heavy features.
+- Use React for popup and options page, bundled with tsup or Vite.
+- Popup window is destroyed on close — persist state to `chrome.storage`.
+- Set a fixed width/height for popup: `min-width: 320px; min-height: 400px`.
+
+## Security
+
+- Never inject user-generated content into web pages without sanitization.
+- Use Content Security Policy (CSP) in manifest.
+- Validate all data from external sources (APIs, messages, storage).
+- Never include API keys or secrets in content scripts — they're visible to the page.
+- Audit `host_permissions` — overly broad permissions trigger Chrome Web Store review delays.
+
+## Development
+
+- Use `chrome://extensions` with Developer Mode for loading unpacked extensions.
+- Enable "Errors" view for debugging service worker issues.
+- Use Chrome DevTools to inspect popup (right-click -> Inspect) and background (service worker link).
+- Hot-reload: rebuild with tsup watch, then click "Update" in `chrome://extensions`.