@1aboveio/skills 0.10.0

package/skills/fullstack/nextjs-fullstack/server-actions.md

@@ -0,0 +1,409 @@
+# React 19 Server Action Patterns
+
+Full-stack form pattern using `useActionState`, `serverAction` wrapper, `withCallbacks`, and Zod validation.
+
+---
+
+## Data Flow
+
+```
+User submits form
+       |
+handleSubmit (react-hook-form + zod)
+       |
+startTransition -> formAction(payload)
+       |
+withCallbacks intercepts call
+       |
+Server action runs (isPending = true)
+  |- beforeAction (auth check)
+  |- Zod validation
+  |- DAL function execution
+  |- onSuccess (revalidatePath)
+       |
+Returns ActionState
+       |
+withCallbacks triggers success/error callback
+  |- onSuccess: toast, reset, close dialog
+  |- onError: toast error, rollback optimistic
+       |
+Component re-renders
+```
+
+---
+
+## Core Utilities
+
+### ActionState Type
+
+```typescript
+// lib/server-action.ts
+export type ActionState<T = unknown> = {
+  success: boolean;
+  message?: string;
+  error?: {
+    code: number;
+    detail?: string;
+  };
+  data?: T;
+};
+```
+
+### withCallbacks
+
+Wraps async actions with success/error callbacks:
+
+```typescript
+type Callbacks<T> = {
+  onSuccess?: (state: T) => void;
+  onError?: (state: T) => void;
+};
+
+export function withCallbacks<Args extends unknown[], T extends ActionState>(
+  fn: (...args: Args) => Promise<T>,
+  callbacks: Callbacks<T>
+): (...args: Args) => Promise<T> {
+  return async (...args: Args) => {
+    const state = await fn(...args);
+
+    if (state?.success === true) {
+      callbacks.onSuccess?.(state);
+    } else if (state?.success === false) {
+      callbacks.onError?.(state);
+    }
+
+    return state;
+  };
+}
+```
+
+### serverAction Factory
+
+```typescript
+export type ServerActionOptions<TInput extends z.ZodTypeAny> = {
+  beforeAction?: () => Promise<void>;
+  onSuccess?: (data: z.infer<TInput>) => Promise<void>;
+};
+
+export function serverAction<TInput extends z.ZodTypeAny, TOutput>(
+  action: (data: z.infer<TInput>) => Promise<TOutput>,
+  schema: TInput,
+  options?: ServerActionOptions<TInput>
+) {
+  return async (
+    _previousState: unknown,
+    payload: z.infer<TInput>
+  ): Promise<ActionState<TOutput>> => {
+    try {
+      if (options?.beforeAction) {
+        await options.beforeAction();
+      }
+
+      const validated = await schema.safeParseAsync(payload);
+      if (!validated.success) {
+        return {
+          success: false,
+          message: "Validation failed",
+          error: { code: 422, detail: validated.error.message },
+        };
+      }
+
+      const result = await action(validated.data);
+
+      if (options?.onSuccess) {
+        await options.onSuccess(validated.data);
+      }
+
+      return { success: true, message: "Success", data: result };
+    } catch (error: unknown) {
+      console.error("Server action error:", error);
+      return {
+        success: false,
+        message: error instanceof Error ? error.message : "Error occurred",
+        error: { code: 500 },
+      };
+    }
+  };
+}
+```
+
+---
+
+## Authentication Hooks
+
+```typescript
+// lib/require-auth.ts
+"use server";
+
+import { auth } from "@/lib/auth";
+import { headers } from "next/headers";
+import { cache } from "react";
+import prisma from "@/lib/prisma";
+
+export const getSession = cache(async () => {
+  return await auth.api.getSession({ headers: await headers() });
+});
+
+export async function requireAuth() {
+  const session = await getSession();
+  if (!session?.user?.id) {
+    throw new Error("Unauthorized");
+  }
+}
+
+export async function requireAdmin() {
+  const session = await getSession();
+  if (!session?.user?.id) throw new Error("Unauthorized");
+
+  const user = await prisma.user.findUnique({
+    where: { id: session.user.id },
+    select: { role: true },
+  });
+
+  if (user?.role !== "admin") throw new Error("Admin required");
+}
+
+export function requireOrgAccess(organizationId: string) {
+  return async () => {
+    const session = await getSession();
+    if (!session?.user?.id) throw new Error("Unauthorized");
+
+    const membership = await prisma.organizationMember.findFirst({
+      where: { userId: session.user.id, organizationId },
+    });
+
+    if (!membership) throw new Error("No access");
+  };
+}
+```
+
+---
+
+## Server Action Definition
+
+```typescript
+// app/dashboard/actions.ts
+"use server";
+
+import { revalidatePath } from "next/cache";
+import { serverAction } from "@/lib/server-action";
+import { requireAuth, requireAdmin } from "@/lib/require-auth";
+import { createOrganizationDAL, deleteOrganizationDAL } from "@/dal/organization";
+import { createOrgSchema, deleteOrgSchema } from "@/types/organization";
+
+// Basic with auth + revalidation
+export const createOrganization = serverAction(
+  createOrganizationDAL,
+  createOrgSchema,
+  {
+    beforeAction: requireAuth,
+    onSuccess: async () => revalidatePath("/organization"),
+  }
+);
+
+// Admin-only
+export const deleteOrganization = serverAction(
+  deleteOrganizationDAL,
+  deleteOrgSchema,
+  {
+    beforeAction: requireAdmin,
+    onSuccess: async () => revalidatePath("/organization"),
+  }
+);
+```
+
+---
+
+## Client Component: Basic Form
+
+```tsx
+"use client";
+
+import { startTransition, useActionState, useMemo, useState } from "react";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { toast } from "sonner";
+import { z } from "zod";
+import { withCallbacks } from "@/lib/server-action";
+
+const schema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+});
+type FormData = z.infer<typeof schema>;
+
+interface Props {
+  action: (state: unknown, payload: FormData) => Promise<ActionState>;
+  onSuccess?: () => void;
+}
+
+export function CreateUserForm({ action, onSuccess }: Props) {
+  const { register, handleSubmit, reset, formState: { errors } } = useForm<FormData>({
+    resolver: zodResolver(schema),
+  });
+  const [open, setOpen] = useState(false);
+
+  // 1. Wrap with callbacks (memoize when deps change)
+  const wrappedAction = useMemo(
+    () => withCallbacks(action, {
+      onSuccess: (state) => {
+        toast.success(state.message || "Created");
+        reset();
+        onSuccess?.();
+        setOpen(false);
+      },
+      onError: (state) => {
+        toast.error(state.message || "Failed");
+      },
+    }),
+    [action, reset, onSuccess]
+  );
+
+  // 2. Use wrapped action
+  const [, formAction, isPending] = useActionState(wrappedAction, undefined);
+
+  // 3. Submit with startTransition
+  function onSubmit(data: FormData) {
+    startTransition(() => formAction(data));
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register("name")} />
+      {errors.name && <p>{errors.name.message}</p>}
+      <input {...register("email")} type="email" />
+      {errors.email && <p>{errors.email.message}</p>}
+      <button disabled={isPending}>Save</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Optimistic Updates
+
+```tsx
+"use client";
+
+import { startTransition, useActionState, useState } from "react";
+import { withCallbacks } from "@/lib/server-action";
+import { toast } from "sonner";
+
+export function StatusToggle({ initialEnabled, action }) {
+  const [enabled, setEnabled] = useState(initialEnabled);
+  const [previousEnabled, setPreviousEnabled] = useState(initialEnabled);
+
+  const [, toggleAction, isPending] = useActionState(
+    withCallbacks(action, {
+      onSuccess: () => toast.success("Updated"),
+      onError: (result) => {
+        toast.error(result.message);
+        setEnabled(previousEnabled); // Rollback
+      },
+    }),
+    null
+  );
+
+  function onToggle() {
+    setPreviousEnabled(enabled);  // Save for rollback
+    setEnabled(!enabled);         // Optimistic update
+
+    startTransition(() => {
+      toggleAction({ enabled: !enabled });
+    });
+  }
+
+  return (
+    <button onClick={onToggle} disabled={isPending}>
+      {enabled ? "Enabled" : "Disabled"}
+    </button>
+  );
+}
+```
+
+---
+
+## Auth Forms (Direct Client)
+
+For auth client calls (not DAL):
+
+```tsx
+"use client";
+
+import { startTransition, useActionState, useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+import { authClient } from "@/lib/auth-client";
+import type { ActionState } from "@/lib/server-action";
+
+const loginSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+export function LoginForm() {
+  const router = useRouter();
+  const { handleSubmit, register } = useForm({
+    resolver: zodResolver(loginSchema),
+  });
+
+  const [state, formAction, isPending] = useActionState<ActionState, FormData>(
+    async (prev, data) => {
+      const result = await authClient.signIn.email(data);
+      if (result.error) {
+        return { success: false, message: result.error.message };
+      }
+      return { success: true, data: result.data };
+    },
+    { success: false }
+  );
+
+  useEffect(() => {
+    if (state.success) router.push("/dashboard");
+  }, [state, router]);
+
+  function onSubmit(data) {
+    startTransition(() => formAction(data));
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register("email")} type="email" />
+      <input {...register("password")} type="password" />
+      {!state.success && state.message && <p>{state.message}</p>}
+      <button disabled={isPending}>Log in</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Key Rules
+
+| Rule | Implementation |
+|------|----------------|
+| Always use `startTransition` | Prevents UI blocking |
+| Wrap with `useMemo` | When callbacks have changing deps |
+| Pass action as prop | Dependency injection |
+| Zod validation | Server in serverAction, client in react-hook-form |
+| Toast in withCallbacks | Keep UI feedback in callbacks |
+| Revalidate in serverAction | Cache invalidation via onSuccess |
+| Optimistic updates | Store previous, update UI, rollback on error |
+| Auth in beforeAction | Use requireAuth/requireAdmin hooks |
+
+---
+
+## When to Use Each Approach
+
+| Use Case | Approach |
+|----------|----------|
+| Database mutations | `serverAction` + DAL |
+| Auth client calls | Inline async in `useActionState` |
+| API routes | Inline async in `useActionState` |
+| Sensitive operations | `serverAction` with `beforeAction` |
+| Cookie/session access | `serverAction` |
+| Public forms | `serverAction` without `beforeAction` |

package/skills/fullstack/prisma-setup/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/fullstack/prisma-setup/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: prisma-setup
+description: Use when adding or debugging Prisma with PostgreSQL, Next.js, or Turborepo, including schema.prisma, prisma.config.ts, client generation, migrations, seeds, relations, adapters, and DAL/database-layer setup. Triggers on phrases like "Prisma schema", "prisma migrate", "schema.prisma", "seed the database", "PrismaClient error", "relation issue", or "database layer".
+---
+
+# Prisma v7 Setup Guide
+
+**Prisma ORM v7** | **PostgreSQL** | **@prisma/adapter-pg**
+
+## Reference Guides
+
+- [Next.js + Prisma v7](nextjs.md) - Standalone Next.js setup
+- [Turborepo + Prisma v7](turborepo.md) - Monorepo with shared DB package
+
+---
+
+## Critical Prisma v7 Requirements
+
+### Generator Configuration
+
+```prisma
+generator client {
+  provider = "prisma-client"           # NOT "prisma-client-js"
+  output   = "../app/generated/prisma" # Custom output REQUIRED
+}
+
+datasource db {
+  provider = "postgresql"
+  # NO url here - moved to prisma.config.ts
+}
+```
+
+### Client Import Path
+
+```typescript
+// CORRECT - include /client at the end
+import { PrismaClient } from "../app/generated/prisma/client"
+
+// WRONG - missing /client
+import { PrismaClient } from "../app/generated/prisma"
+
+// WRONG - default location
+import { PrismaClient } from "@prisma/client"
+```
+
+### Prisma Config (prisma.config.ts)
+
+```typescript
+import "dotenv/config"  // REQUIRED at top
+import { defineConfig, env } from "prisma/config"
+
+export default defineConfig({
+  schema: "prisma/schema.prisma",
+  migrations: {
+    path: "prisma/migrations",
+  },
+  // NO engine property - removed in v7
+  datasource: {
+    url: env("DATABASE_URL"),
+  },
+})
+```
+
+### Client Singleton
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from "../app/generated/prisma/client"
+import { PrismaPg } from "@prisma/adapter-pg"
+
+const adapter = new PrismaPg({
+  connectionString: process.env.DATABASE_URL!,
+})
+
+const globalForPrisma = global as unknown as { prisma: PrismaClient }
+
+const prisma = globalForPrisma.prisma || new PrismaClient({ adapter })
+
+if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma
+
+export default prisma
+```
+
+---
+
+## Deprecated Patterns (NEVER USE)
+
+```typescript
+// DEPRECATED - prisma-client-js
+generator client {
+  provider = "prisma-client-js"
+}
+
+// DEPRECATED - url in datasource
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+// DEPRECATED - engine property
+export default defineConfig({
+  engine: "classic",  // REMOVED in v7
+})
+
+// DEPRECATED - accelerateUrl
+new PrismaClient({
+  accelerateUrl: process.env.DATABASE_URL,
+})
+
+// DEPRECATED - Accelerate extension (for TCP connections)
+import { withAccelerate } from "@prisma/extension-accelerate"
+```
+
+---
+
+## Version Requirements
+
+- **Node.js:** 20.19+ (Node 18 NOT supported)
+- **TypeScript:** 5.4.0+
+- **Prisma:** 7.0.0+
+
+---
+
+## Installation
+
+```bash
+# Dev dependencies
+npm install prisma tsx --save-dev
+
+# Production dependencies
+npm install @prisma/adapter-pg @prisma/client dotenv
+```
+
+---
+
+## Database URL
+
+Must use standard TCP URL:
+
+```env
+# CORRECT
+DATABASE_URL="postgres://user:pass@host:5432/db"
+
+# WRONG - HTTP URL
+DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/..."
+```
+
+---
+
+## Common Commands
+
+```bash
+# Generate client
+npx prisma generate
+
+# Push schema (no migrations)
+npx prisma db push
+
+# Create migration
+npx prisma migrate dev --name your_migration
+
+# Open Studio
+npx prisma studio
+```
+
+---
+
+## Verification Checklist
+
+Before writing any Prisma code, verify:
+
+1. `provider = "prisma-client"` (not prisma-client-js)
+2. Custom `output` path specified
+3. Import from `generated/prisma/client` (with /client)
+4. `import "dotenv/config"` in prisma.config.ts
+5. Using `@prisma/adapter-pg` with `adapter` property
+6. No `url` in datasource block
+7. No `engine` property in config
+8. DATABASE_URL uses `postgres://` (not `prisma+postgres://`)
+9. All DB operations wrapped in try-catch