@folpe/loom 0.2.0 → 0.3.0

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

@@ -1,14 +1,21 @@
 ---
 name: chrome-extension-patterns
-description: "Chrome extension development patterns for Manifest V3, content scripts, popup UI, and service workers. Use when building browser extensions."
-allowed-tools: "Read, Write, Edit, Glob, Grep"
+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
 
-- Always use **Manifest V3** — Manifest V2 is deprecated.
 - Define minimal permissions — request only what the extension needs:
   ```json
   {
@@ -65,8 +72,8 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 
 ## Messaging
 
-- Use `chrome.runtime.sendMessage` for popup/options ↔ background communication.
-- Use `chrome.tabs.sendMessage` for background → content script communication.
+- 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 =
@@ -94,5 +101,5 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 
 - 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).
+- 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`.

package/data/skills/cli-development/SKILL.md

@@ -1,11 +1,19 @@
 ---
 name: cli-development
-description: "CLI tool development patterns for Node.js with Commander.js, terminal UX, and npm distribution. Use when building command-line tools."
-allowed-tools: "Read, Write, Edit, Glob, Grep"
+description: "CLI tool development patterns for Node.js with Commander.js, terminal UX, error handling, and npm distribution. Use when building command-line tools, adding CLI commands, implementing terminal prompts, or bundling CLI binaries for distribution."
 ---
 
 # CLI Development Patterns
 
+## Critical Rules
+
+- **Use `stdout` for data, `stderr` for logs** — never mix output channels.
+- **Exit with proper codes** — `0` success, `1` runtime error, `2` usage error.
+- **Never show raw stack traces** — log them with `--verbose` flag only.
+- **Respect `NO_COLOR`** — check `process.env.NO_COLOR` before using colors.
+- **Validate config with Zod** — fail fast with clear error on invalid config.
+- **Confirm destructive actions** — always prompt before irreversible operations.
+
 ## Project Structure
 
 ```
@@ -71,7 +79,7 @@ src/
 
 - Show a spinner for long operations (use `ora` or `nanospinner`).
 - Use progress bars for multi-step or percentage-based operations.
-- Confirm destructive actions with a prompt (use `@inquirer/prompts`):
+- Confirm destructive actions with a prompt (use `@inquirer/prompts` or `@clack/prompts`):
   ```ts
   const confirmed = await confirm({ message: 'Delete all files?' })
   if (!confirmed) process.exit(0)

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

@@ -0,0 +1,166 @@
+---
+name: drizzle-patterns
+description: "Drizzle ORM patterns for schema design, migrations, transactions, and DAO functions. Use when creating database schemas, writing queries, implementing transactions, or working with PostgreSQL via Drizzle."
+---
+
+# Drizzle ORM Patterns
+
+## Critical Rules
+
+- **Infer types from schema** — never duplicate type definitions manually.
+- **Use `limit()` on all queries** — never fetch unbounded result sets.
+- **Select only needed columns** — avoid `select()` with no arguments on large tables.
+- **Never nest transactions** — keep transactions short with no external API calls inside.
+- **Never edit generated migration files** — review SQL before applying in production.
+- **Add indexes** on columns used in `WHERE`, `JOIN`, and `ORDER BY`.
+
+## Schema Design
+
+- Define schemas in `src/schema/` with one file per entity.
+- Export all tables from `src/schema/index.ts` barrel file.
+- Use `pgTable` for table definitions with typed columns.
+
+```ts
+// src/schema/user.ts
+import { pgTable, uuid, text, timestamp, boolean } from "drizzle-orm/pg-core";
+
+export const users = pgTable("users", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  email: text("email").notNull().unique(),
+  name: text("name").notNull(),
+  role: text("role", { enum: ["USER", "ADMIN"] }).notNull().default("USER"),
+  emailVerified: boolean("email_verified").notNull().default(false),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+});
+```
+
+## Relations
+
+- Define relations separately using `relations()`:
+
+```ts
+import { relations } from "drizzle-orm";
+
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+  organizations: many(organizationMembers),
+}));
+
+export const postsRelations = relations(posts, ({ one }) => ({
+  author: one(users, { fields: [posts.authorId], references: [users.id] }),
+}));
+```
+
+## Database Client
+
+```ts
+// src/lib/db.ts
+import { drizzle } from "drizzle-orm/node-postgres";
+import * as schema from "@/schema";
+
+export const db = drizzle(process.env.DATABASE_URL!, { schema });
+```
+
+## Query Patterns
+
+- Use the query builder for complex reads:
+```ts
+const result = await db.query.users.findMany({
+  where: eq(users.role, "ADMIN"),
+  with: { posts: true },
+  orderBy: [desc(users.createdAt)],
+  limit: 20,
+});
+```
+
+- Use `select()` for simple reads with specific columns:
+```ts
+const result = await db.select({
+  id: users.id,
+  name: users.name,
+}).from(users).where(eq(users.role, "ADMIN"));
+```
+
+## Transactions
+
+- Wrap multi-table writes in transactions:
+```ts
+await db.transaction(async (tx) => {
+  const [org] = await tx.insert(organizations).values({ name }).returning();
+  await tx.insert(organizationMembers).values({
+    organizationId: org.id,
+    userId: currentUser.id,
+    role: "OWNER",
+  });
+});
+```
+
+## DAO Pattern
+
+- Create DAO functions in `src/dal/` for reusable queries:
+
+```ts
+// src/dal/user.dal.ts
+export async function findUserById(id: string) {
+  return db.query.users.findFirst({
+    where: eq(users.id, id),
+  });
+}
+
+export async function findUsersByOrg(orgId: string) {
+  return db.select()
+    .from(users)
+    .innerJoin(orgMembers, eq(orgMembers.userId, users.id))
+    .where(eq(orgMembers.orgId, orgId));
+}
+
+export async function createUser(data: NewUser) {
+  const [user] = await db.insert(users).values(data).returning();
+  return user;
+}
+
+export async function updateUser(id: string, data: Partial<NewUser>) {
+  const [user] = await db.update(users)
+    .set({ ...data, updatedAt: new Date() })
+    .where(eq(users.id, id))
+    .returning();
+  return user;
+}
+
+export async function deleteUser(id: string) {
+  await db.delete(users).where(eq(users.id, id));
+}
+```
+
+## Migrations
+
+- Generate migrations with `npx drizzle-kit generate`.
+- Apply with `npx drizzle-kit migrate`.
+- Use `drizzle-kit push` only in development for quick iteration.
+- Review generated SQL before applying in production.
+
+## Type Inference
+
+```ts
+import type { InferSelectModel, InferInsertModel } from "drizzle-orm";
+
+export type User = InferSelectModel<typeof users>;
+export type NewUser = InferInsertModel<typeof users>;
+```
+
+## Performance
+
+- Add indexes on columns used in `WHERE`, `JOIN`, and `ORDER BY`:
+```ts
+import { index } from "drizzle-orm/pg-core";
+
+export const posts = pgTable("posts", {
+  // columns...
+}, (table) => [
+  index("posts_author_idx").on(table.authorId),
+  index("posts_created_at_idx").on(table.createdAt),
+]);
+```
+
+- Use `prepare()` for frequently executed queries.

package/data/skills/env-validation/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: env-validation
+description: "Environment variable validation with Zod schemas and type-safe access. Use when configuring environment variables, adding new secrets, or setting up project configuration."
+---
+
+# Environment Variable Validation
+
+## Critical Rules
+
+- **Validate at startup** — crash early if env vars are missing/invalid.
+- **Single source of truth** — `src/env.ts` is the only place to access env vars.
+- **Never use `process.env` directly** — always import from `@/env`.
+- **Type-safe prefixes** — validate format (e.g., `startsWith("sk_")` for Stripe keys).
+- **Maintain `.env.example`** — document all required variables without values.
+- **Never commit secrets** — `.env.local` and `.env.production` are gitignored.
+
+## Schema Definition
+
+Validate all environment variables at startup with a Zod schema:
+
+```ts
+// src/env.ts
+import { z } from "zod";
+
+const envSchema = z.object({
+  // Database
+  DATABASE_URL: z.string().url(),
+
+  // Auth
+  BETTER_AUTH_SECRET: z.string().min(32),
+  BETTER_AUTH_URL: z.string().url(),
+
+  // Email
+  RESEND_API_KEY: z.string().startsWith("re_"),
+
+  // Stripe
+  STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
+  STRIPE_WEBHOOK_SECRET: z.string().startsWith("whsec_"),
+  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith("pk_"),
+
+  // App
+  NEXT_PUBLIC_APP_URL: z.string().url(),
+  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
+});
+
+export const env = envSchema.parse(process.env);
+```
+
+## Usage
+
+Always import from `@/env` — never access `process.env` directly:
+
+```ts
+// Good
+import { env } from "@/env";
+const db = drizzle(env.DATABASE_URL);
+
+// Bad — unvalidated, untyped
+const db = drizzle(process.env.DATABASE_URL!);
+```
+
+## Client-Side Variables
+
+Only `NEXT_PUBLIC_` prefixed variables are available in the browser:
+
+```ts
+// src/env.ts
+const clientSchema = z.object({
+  NEXT_PUBLIC_APP_URL: z.string().url(),
+  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith("pk_"),
+});
+
+const serverSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  BETTER_AUTH_SECRET: z.string().min(32),
+  RESEND_API_KEY: z.string().startsWith("re_"),
+  // ...server-only vars
+});
+
+// Merge for full validation
+const envSchema = serverSchema.merge(clientSchema);
+
+export const env = envSchema.parse(process.env);
+
+// Client-only export for safe use in client components
+export const clientEnv = clientSchema.parse({
+  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
+});
+```
+
+## .env Files
+
+```
+.env                  # Shared defaults (committed)
+.env.local            # Local overrides (gitignored)
+.env.development      # Dev-specific
+.env.production       # Prod-specific (gitignored)
+.env.test             # Test-specific
+```
+
+### .env.example
+
+Maintain a `.env.example` with all required variables (no values):
+
+```env
+# Database
+DATABASE_URL=
+
+# Auth
+BETTER_AUTH_SECRET=
+BETTER_AUTH_URL=
+
+# Email
+RESEND_API_KEY=
+
+# Stripe
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
+
+# App
+NEXT_PUBLIC_APP_URL=
+```
+
+## Startup Validation
+
+The `env.ts` import triggers validation. Import it early in your app:
+
+```ts
+// src/app/layout.tsx
+import "@/env"; // Validates env vars at startup
+```
+
+If validation fails, the app crashes immediately with a clear error:
+
+```
+ZodError: [
+  { path: ["DATABASE_URL"], message: "Required" },
+  { path: ["RESEND_API_KEY"], message: "Invalid" }
+]
+```