@devmunna/agent-skillkit 0.1.0

package/skills/nextjs-fullstack/references/server-components.md

@@ -0,0 +1,190 @@
+# Server Components Reference
+
+---
+
+## Decision: Server vs Client Component
+
+```
+Does the component need:
+  useState / useEffect / useRef / useContext?    → 'use client'
+  onClick / onChange / onSubmit?                → 'use client'
+  window / localStorage / document?             → 'use client'
+  useActionState / useOptimistic / useFormStatus? → 'use client'
+  Third-party client-only library?              → 'use client'
+  ─────────────────────────────────────────────
+  None of the above?                            → Server Component (default)
+```
+
+**Push 'use client' as far down the tree as possible.** A page can be a Server Component that renders one or two leaf Client Components for interactivity.
+
+---
+
+## Data Fetching in Server Components
+
+Fetch directly — no useEffect, no loading state, no API client:
+
+```tsx
+// app/(dashboard)/users/page.tsx
+import { db }          from '@/lib/db';
+import { auth }        from '@/lib/auth';
+import { notFound }    from 'next/navigation';
+import { UserList }    from '@/features/users/components/UserList';
+import { CreateButton } from '@/features/users/components/CreateButton';
+
+export default async function UsersPage() {
+  const session = await auth();
+  if (!session) redirect('/auth/login');
+
+  const users = await db.user.findMany({
+    select: { id: true, name: true, email: true, role: true, createdAt: true },
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return (
+    <div>
+      <div className="header">
+        <h1>Users</h1>
+        <CreateButton />   {/* Client Component */}
+      </div>
+      <UserList users={users} />
+    </div>
+  );
+}
+```
+
+---
+
+## Parallel Data Fetching
+
+Use `Promise.all` for independent queries — runs them concurrently:
+
+```tsx
+export default async function DashboardPage() {
+  const [users, products, stats] = await Promise.all([
+    db.user.count(),
+    db.product.count(),
+    getStats(),
+  ]);
+
+  return <Dashboard users={users} products={products} stats={stats} />;
+}
+```
+
+---
+
+## Dynamic Route — params as Promise (Next.js 15)
+
+```tsx
+// app/(dashboard)/users/[id]/page.tsx
+import { notFound } from 'next/navigation';
+import { db }       from '@/lib/db';
+
+interface Props {
+  params: Promise<{ id: string }>;
+}
+
+export default async function UserDetailPage({ params }: Props) {
+  const { id } = await params;
+
+  const user = await db.user.findUnique({
+    where:  { id },
+    select: { id: true, name: true, email: true, role: true, createdAt: true },
+  });
+
+  if (!user) notFound();
+
+  return <UserDetail user={user} />;
+}
+```
+
+---
+
+## Streaming with Suspense
+
+Wrap slow data sources in `<Suspense>` to stream content progressively:
+
+```tsx
+// app/(dashboard)/users/page.tsx
+import { Suspense } from 'react';
+
+export default function UsersPage() {
+  return (
+    <div>
+      <h1>Users</h1>
+      {/* Header renders immediately; list streams in */}
+      <Suspense fallback={<UserListSkeleton />}>
+        <UserListAsync />
+      </Suspense>
+    </div>
+  );
+}
+
+// Separate async component wraps the slow fetch
+async function UserListAsync() {
+  const users = await db.user.findMany(); // waits here, not in the parent
+  return <UserList users={users} />;
+}
+```
+
+---
+
+## Passing Server Data to Client Components
+
+Server Components can pass serializable props to Client Components:
+
+```tsx
+// Server Component (parent)
+export default async function UsersPage() {
+  const users = await db.user.findMany();
+
+  return (
+    <UserDataTable
+      users={users}           // serialized and sent to client
+      initialPage={1}
+    />
+  );
+}
+
+// 'use client' (child) — receives pre-fetched data
+'use client';
+export function UserDataTable({ users, initialPage }: Props) {
+  const [page, setPage] = useState(initialPage);
+  // uses users from server + client-side pagination
+}
+```
+
+**Cannot pass:** functions, class instances, non-serializable objects.
+
+---
+
+## Server Component Composition Patterns
+
+```tsx
+// Composition: Server wraps Client
+// ✅ Works — Server Component passes RSC children to Client
+export default async function Layout({ children }: { children: React.ReactNode }) {
+  const session = await auth();
+  return (
+    <ClientSidebar session={session}>
+      {children}
+    </ClientSidebar>
+  );
+}
+
+// ✅ Works — Server Component imported in another Server Component
+import { ServerNav } from '@/components/server/ServerNav';
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <ServerNav />
+        {children}
+      </body>
+    </html>
+  );
+}
+
+// ❌ Cannot — import Server Component inside 'use client' component
+'use client';
+import { ServerComponent } from './ServerComponent'; // error: server-only
+```

package/skills/node-base/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: node-base
+version: 1.0.0
+description: >
+  Base Node.js development standards. Apply this skill to every Node.js project regardless of framework. Covers async patterns, error handling foundations, environment configuration, file/folder conventions, logging, security defaults, and code quality rules.
+stack: [node]
+depends: []
+---
+
+# Node.js Base Skill
+
+Baseline standards for every Node.js project. Framework-agnostic. Superseded by more specific skills (express-mvc-prisma, fastify-rest) when those are active.
+
+---
+
+## Project Conventions
+
+### Module system
+- Use ES Modules (`"type": "module"` in package.json) for new projects
+- Use `.js` extensions in all import paths
+- Never mix `require()` and `import` in the same codebase
+
+### File naming
+- `kebab-case` for all files and directories
+- No spaces, no underscores in file names
+- Test files: `*.test.js` or `*.spec.js` adjacent to source
+
+### Folder structure (generic)
+```
+src/
+├── config/        # Env, DB, third-party clients
+├── modules/       # Feature-grouped domain logic
+├── middlewares/   # Cross-cutting concerns
+├── utils/         # Pure utilities (no side effects)
+└── types/         # Shared type definitions (TS projects)
+```
+
+---
+
+## Environment Variables
+
+Always validate env at startup. Never read `process.env` outside the config module.
+
+```js
+// src/config/env.js — minimal template
+import { z } from 'zod';
+import 'dotenv/config';
+
+const schema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().default(3000),
+});
+
+const result = schema.safeParse(process.env);
+if (!result.success) {
+  console.error('❌ Missing env vars:', result.error.flatten().fieldErrors);
+  process.exit(1);
+}
+
+export const env = result.data;
+```
+
+---
+
+## Async Patterns
+
+- Always `async/await` — no `.then()/.catch()` chains
+- Never swallow errors with empty `catch` blocks
+- Top-level `await` is supported in ES Modules
+
+```js
+// Good
+const data = await fetchData();
+
+// Bad
+fetchData().then(data => { ... });
+
+// Never
+try { ... } catch (e) {}  // swallowed error
+```
+
+---
+
+## Error Handling
+
+- Create an `AppError` class for operational errors (expected, safe to expose to client)
+- Unhandled rejections and exceptions must crash the process in production
+
+```js
+// src/utils/AppError.js
+export class AppError extends Error {
+  constructor(message, statusCode = 500) {
+    super(message);
+    this.statusCode = statusCode;
+    this.isOperational = true;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+// Crash on unhandled rejections (in server.js / entry point)
+process.on('unhandledRejection', (reason) => {
+  console.error('Unhandled Rejection:', reason);
+  process.exit(1);
+});
+```
+
+---
+
+## Logging
+
+- Use `console.error()` for errors (goes to stderr)
+- Use `console.log()` for info (goes to stdout)
+- Include context: `[module] message` format
+- Never log passwords, tokens, or PII
+
+```js
+console.error('[auth] Login failed:', email); // OK — no password
+console.log('[server] Listening on port', port);
+```
+
+---
+
+## Security Defaults
+
+Always apply these in HTTP servers:
+- Disable `X-Powered-By` header: `app.disable('x-powered-by')`
+- Validate and sanitize all user input before using it
+- Never use `eval()`, `new Function()`, or `vm.runInThisContext()` with user input
+- Use `crypto.randomBytes()` or `crypto.randomUUID()` for tokens — never `Math.random()`
+
+---
+
+## Code Quality Rules
+
+- Max function length: ~30 lines. Extract if longer
+- One export concept per file
+- Pure utility functions must be side-effect-free
+- No `var` — always `const`, use `let` only when reassignment is required
+- No `any` in TypeScript — use `unknown` and narrow

package/skills/prisma-orm/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: prisma-orm
+version: 2.0.0
+description: >
+  Apply this skill for any task involving Prisma ORM: designing schemas, writing migrations, querying data, handling relations, transactions, optimizing queries, or seeding. Triggers: "add Prisma to project", "design schema", "write a query", "handle Prisma errors", "transaction", "migrate database", "Prisma relations", "seeding", "Prisma v5".
+stack: [prisma, postgresql]
+depends: []
+---
+
+# Prisma ORM v5 — Production Skill
+
+**Version target:** Prisma v5 · PostgreSQL · Node.js 20+ (ESM)
+
+---
+
+## Installation
+
+```bash
+npm install @prisma/client
+npm install -D prisma
+npx prisma init --datasource-provider postgresql
+```
+
+---
+
+## Schema Conventions
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(uuid())     // UUID always, never autoincrement
+  email     String   @unique
+  name      String
+  password  String
+  role      Role     @default(USER)           // enum for fixed value sets
+  posts     Post[]
+  createdAt DateTime @default(now())          // always add timestamps
+  updatedAt DateTime @updatedAt
+
+  @@map("users")                              // snake_case table name always
+}
+
+model Post {
+  id        String   @id @default(uuid())
+  title     String
+  body      String
+  published Boolean  @default(false)
+  authorId  String
+  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([authorId])                         // index every foreign key
+  @@map("posts")
+}
+
+enum Role {
+  USER
+  ADMIN
+  MANAGER
+}
+```
+
+**Schema rules (non-negotiable):**
+- `@id @default(uuid())` on every model — never `@default(autoincrement())`
+- `createdAt` + `updatedAt` on every model
+- `@@map("snake_case")` on every model
+- `@@index([fk])` on every foreign key field
+- Enums for any column with a fixed set of values
+
+---
+
+## Prisma Singleton
+
+```js
+// src/config/db.js (Express) or src/lib/db.ts (Next.js)
+import { PrismaClient } from '@prisma/client';
+import { isDev }        from './env.js';
+
+const globalForPrisma = globalThis;
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({ log: isDev ? ['query', 'warn', 'error'] : ['error'] });
+
+if (isDev) globalForPrisma.prisma = prisma;
+
+export default prisma;
+```
+
+---
+
+## Service-Layer Queries (4-file pattern — no repository)
+
+Services call Prisma directly. No separate repository file.
+
+```js
+// modules/post/post.service.js
+import prisma          from '../../config/db.js';
+import { Prisma }      from '@prisma/client';
+import { AppError }    from '../../utils/AppError.js';
+
+export const postService = {
+  async getAll({ page = 1, limit = 10, authorId } = {}) {
+    const skip  = (page - 1) * limit;
+    const where = authorId ? { authorId } : {};
+
+    const [data, total] = await prisma.$transaction([
+      prisma.post.findMany({
+        where,
+        skip,
+        take: limit,
+        orderBy: { createdAt: 'desc' },
+        select: {
+          id: true, title: true, published: true, createdAt: true,
+          author: { select: { id: true, name: true } },
+        },
+      }),
+      prisma.post.count({ where }),
+    ]);
+
+    return { data, total, page, limit };
+  },
+
+  async getById(id) {
+    const post = await prisma.post.findUnique({
+      where:   { id },
+      include: { author: { select: { id: true, name: true } } },
+    });
+    if (!post) throw new AppError('Post not found', 404);
+    return post;
+  },
+
+  async create(data) {
+    try {
+      return await prisma.post.create({ data });
+    } catch (err) {
+      if (err instanceof Prisma.PrismaClientKnownRequestError) {
+        if (err.code === 'P2002') throw new AppError('Duplicate entry', 409);
+        if (err.code === 'P2003') throw new AppError('Related record not found', 400);
+      }
+      throw err;
+    }
+  },
+
+  async update(id, data) {
+    try {
+      return await prisma.post.update({ where: { id }, data });
+    } catch (err) {
+      if (err instanceof Prisma.PrismaClientKnownRequestError) {
+        if (err.code === 'P2025') throw new AppError('Post not found', 404);
+      }
+      throw err;
+    }
+  },
+
+  async remove(id) {
+    await prisma.post.delete({ where: { id } });
+  },
+};
+```
+
+---
+
+## Prisma Error Codes — Handle in Service Layer
+
+| Code | Meaning | Response |
+|------|---------|--------|
+| P2002 | Unique constraint violation | 409 Conflict |
+| P2025 | Record not found (update/delete) | 404 Not Found |
+| P2003 | Foreign key constraint failed | 400 Bad Request |
+| P2014 | Relation violation | 400 Bad Request |
+
+The global `errorHandler` also catches raw `PrismaClientKnownRequestError` as a fallback.
+
+---
+
+## Transactions
+
+Use `$transaction` for multi-step writes that must be atomic:
+
+```js
+// Batch (parallel) — read count + list
+const [data, total] = await prisma.$transaction([
+  prisma.post.findMany({ skip, take }),
+  prisma.post.count(),
+]);
+
+// Interactive (sequential) — reads depend on previous writes
+const result = await prisma.$transaction(async (tx) => {
+  const order = await tx.order.create({ data: orderData });
+
+  await tx.product.update({
+    where: { id: orderData.productId },
+    data:  { stock: { decrement: orderData.quantity } },
+  });
+
+  await tx.payment.create({
+    data: { orderId: order.id, amount: orderData.total },
+  });
+
+  return order;
+});
+```
+
+---
+
+## Query Optimization
+
+```js
+// Select only needed fields — never return password or secrets
+prisma.user.findMany({
+  select: { id: true, name: true, email: true, role: true },
+})
+
+// Include relations with select — avoid N+1 and fetching unnecessary data
+prisma.post.findMany({
+  include: {
+    author:   { select: { id: true, name: true } },
+    _count:   { select: { comments: true } },    // count without loading records
+  },
+})
+
+// Cursor-based pagination for large datasets
+prisma.post.findMany({
+  take:   10,
+  skip:   1,                     // skip the cursor itself
+  cursor: { id: lastId },
+  orderBy: { createdAt: 'asc' },
+})
+```
+
+---
+
+## Relation Patterns
+
+```prisma
+// One-to-many
+model Category {
+  id    String  @id @default(uuid())
+  name  String
+  posts Post[]
+
+  @@map("categories")
+}
+
+model Post {
+  categoryId String?
+  category   Category? @relation(fields: [categoryId], references: [id])
+
+  @@index([categoryId])
+  @@map("posts")
+}
+
+// Many-to-many (explicit join table)
+model Post {
+  tags PostTag[]
+}
+
+model Tag {
+  posts PostTag[]
+}
+
+model PostTag {
+  postId String
+  tagId  String
+  post   Post   @relation(fields: [postId], references: [id], onDelete: Cascade)
+  tag    Tag    @relation(fields: [tagId],  references: [id], onDelete: Cascade)
+
+  @@id([postId, tagId])
+  @@map("post_tags")
+}
+```
+
+---
+
+## Migration Commands
+
+```bash
+npx prisma migrate dev --name <description>   # create + apply (dev only)
+npx prisma migrate deploy                      # apply pending (production)
+npx prisma migrate reset                       # reset + reseed (dev only)
+npx prisma generate                            # regenerate Prisma Client
+npx prisma studio                              # GUI browser
+npx prisma db seed                             # run seed file
+```
+
+---
+
+## Seeding
+
+```js
+// prisma/seed.js
+import { PrismaClient } from '@prisma/client';
+import bcrypt           from 'bcrypt';
+
+const prisma = new PrismaClient();
+
+async function main() {
+  const passwordHash = await bcrypt.hash('password123', 12);
+
+  await prisma.user.upsert({
+    where:  { email: 'admin@example.com' },
+    update: {},
+    create: {
+      email:    'admin@example.com',
+      name:     'Admin',
+      password: passwordHash,
+      role:     'ADMIN',
+    },
+  });
+
+  console.log('Seeding complete');
+}
+
+main()
+  .catch(console.error)
+  .finally(() => prisma.$disconnect());
+```
+
+In `package.json`:
+```json
+{
+  "prisma": { "seed": "node prisma/seed.js" }
+}
+```