@plazmodium/odin 0.3.2-beta → 0.3.4-beta

package/builtin/skills/database/prisma-orm/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: prisma-orm
+description: Prisma ORM expertise for type-safe database access, schema design, migrations, and query optimization
+category: database
+version: "5.x"
+depends_on:
+  - postgresql
+compatible_with:
+  - mysql
+  - nodejs-express
+  - nextjs-dev
+  - typescript
+---
+
+# Prisma ORM Development
+
+## Overview
+
+Prisma is a next-generation ORM for Node.js and TypeScript that provides type-safe database access, automated migrations, and an intuitive data modeling language.
+
+## Project Structure
+
+```
+prisma/
+├── schema.prisma         # Database schema
+├── migrations/           # Migration history
+│   └── 20240115_init/
+│       └── migration.sql
+└── seed.ts               # Database seeding
+
+src/
+├── lib/
+│   └── prisma.ts         # Prisma client singleton
+└── services/
+    └── user.service.ts   # Using Prisma client
+```
+
+## Schema Design
+
+### Basic Schema
+
+```prisma
+// prisma/schema.prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(uuid())
+  email     String   @unique
+  name      String?
+  password  String
+  role      Role     @default(USER)
+  posts     Post[]
+  profile   Profile?
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@map("users")
+}
+
+model Post {
+  id          String   @id @default(uuid())
+  title       String
+  content     String?
+  published   Boolean  @default(false)
+  author      User     @relation(fields: [authorId], references: [id])
+  authorId    String   @map("author_id")
+  categories  Category[]
+  createdAt   DateTime @default(now()) @map("created_at")
+  updatedAt   DateTime @updatedAt @map("updated_at")
+
+  @@index([authorId])
+  @@map("posts")
+}
+
+model Profile {
+  id     String @id @default(uuid())
+  bio    String?
+  avatar String?
+  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+  userId String @unique @map("user_id")
+
+  @@map("profiles")
+}
+
+model Category {
+  id    String @id @default(uuid())
+  name  String @unique
+  posts Post[]
+
+  @@map("categories")
+}
+
+enum Role {
+  USER
+  ADMIN
+  MODERATOR
+}
+```
+
+## Prisma Client Setup
+
+```typescript
+// src/lib/prisma.ts
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined;
+};
+
+export const prisma = globalForPrisma.prisma ?? new PrismaClient({
+  log: process.env.NODE_ENV === 'development'
+    ? ['query', 'error', 'warn']
+    : ['error'],
+});
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma;
+}
+
+export default prisma;
+```
+
+## Common Query Patterns
+
+### CRUD Operations
+
+```typescript
+import prisma from '@/lib/prisma';
+
+// Create
+const user = await prisma.user.create({
+  data: {
+    email: 'user@example.com',
+    name: 'John Doe',
+    password: hashedPassword,
+  },
+});
+
+// Read (single)
+const user = await prisma.user.findUnique({
+  where: { id: userId },
+});
+
+// Read (with relations)
+const userWithPosts = await prisma.user.findUnique({
+  where: { id: userId },
+  include: {
+    posts: true,
+    profile: true,
+  },
+});
+
+// Read (many with filtering)
+const users = await prisma.user.findMany({
+  where: {
+    email: { contains: '@company.com' },
+    role: 'USER',
+  },
+  orderBy: { createdAt: 'desc' },
+  take: 10,
+  skip: 0,
+});
+
+// Update
+const updated = await prisma.user.update({
+  where: { id: userId },
+  data: { name: 'Jane Doe' },
+});
+
+// Delete
+await prisma.user.delete({
+  where: { id: userId },
+});
+```
+
+### Select Specific Fields
+
+```typescript
+const users = await prisma.user.findMany({
+  select: {
+    id: true,
+    email: true,
+    name: true,
+    // password intentionally excluded
+  },
+});
+```
+
+### Nested Writes
+
+```typescript
+// Create user with profile
+const user = await prisma.user.create({
+  data: {
+    email: 'user@example.com',
+    name: 'John',
+    password: hash,
+    profile: {
+      create: {
+        bio: 'Developer',
+      },
+    },
+  },
+  include: { profile: true },
+});
+
+// Create post with categories
+const post = await prisma.post.create({
+  data: {
+    title: 'My Post',
+    content: 'Content...',
+    authorId: userId,
+    categories: {
+      connectOrCreate: [
+        {
+          where: { name: 'Tech' },
+          create: { name: 'Tech' },
+        },
+      ],
+    },
+  },
+});
+```
+
+### Transactions
+
+```typescript
+// Sequential transaction
+const [user, post] = await prisma.$transaction([
+  prisma.user.create({ data: userData }),
+  prisma.post.create({ data: postData }),
+]);
+
+// Interactive transaction
+const result = await prisma.$transaction(async (tx) => {
+  const user = await tx.user.create({ data: userData });
+
+  if (someCondition) {
+    throw new Error('Rollback!');
+  }
+
+  const post = await tx.post.create({
+    data: { ...postData, authorId: user.id },
+  });
+
+  return { user, post };
+});
+```
+
+### Aggregations
+
+```typescript
+// Count
+const count = await prisma.user.count({
+  where: { role: 'USER' },
+});
+
+// Group by
+const postsByUser = await prisma.post.groupBy({
+  by: ['authorId'],
+  _count: { id: true },
+  orderBy: { _count: { id: 'desc' } },
+});
+
+// Aggregate
+const stats = await prisma.post.aggregate({
+  _count: true,
+  _avg: { views: true },
+  _max: { views: true },
+});
+```
+
+## Migrations
+
+```bash
+# Create migration
+npx prisma migrate dev --name add_user_role
+
+# Apply migrations (production)
+npx prisma migrate deploy
+
+# Reset database (development only!)
+npx prisma migrate reset
+
+# Generate client after schema changes
+npx prisma generate
+```
+
+## Best Practices
+
+1. **Use singleton pattern** - Prevent connection pool exhaustion
+2. **Select only needed fields** - Reduce data transfer
+3. **Use transactions for related writes** - Ensure data consistency
+4. **Add indexes for query fields** - `@@index([fieldName])`
+5. **Use `@map` for snake_case** - Keep DB conventions, use camelCase in code
+6. **Archive instead of delete** - Add `isArchived Boolean @default(false)` and `archivedAt DateTime?` for recoverable records. "Soft delete" is a misnomer - use archive terminology to match real-world concepts
+7. **Always include `updatedAt`** - Use `@updatedAt` for automatic tracking
+
+## Gotchas & Pitfalls
+
+- **N+1 queries** - Use `include` or `select` with relations, not separate queries
+- **Connection limits** - Use singleton pattern, especially in serverless
+- **Migration conflicts** - Don't edit existing migrations, create new ones
+- **Type mismatches** - Run `prisma generate` after schema changes
+- **Forgetting indexes** - Add `@@index` for frequently queried fields
+- **BigInt serialization** - JSON.stringify doesn't handle BigInt, convert to string
+
+## Integration with Next.js
+
+```typescript
+// app/api/users/route.ts
+import prisma from '@/lib/prisma';
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  const users = await prisma.user.findMany({
+    select: { id: true, email: true, name: true },
+  });
+  return NextResponse.json(users);
+}
+```
+
+## Seeding
+
+```typescript
+// prisma/seed.ts
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+async function main() {
+  await prisma.user.upsert({
+    where: { email: 'admin@example.com' },
+    update: {},
+    create: {
+      email: 'admin@example.com',
+      name: 'Admin',
+      password: 'hashed_password',
+      role: 'ADMIN',
+    },
+  });
+}
+
+main()
+  .catch((e) => {
+    console.error(e);
+    process.exit(1);
+  })
+  .finally(() => prisma.$disconnect());
+```
+
+```json
+// package.json
+{
+  "prisma": {
+    "seed": "ts-node prisma/seed.ts"
+  }
+}
+```

package/builtin/skills/database/redis/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: redis
+description: Redis in-memory data store patterns for caching, sessions, queues, and real-time features
+category: database
+version: "7.x"
+compatible_with:
+  - nodejs-express
+  - nodejs-fastify
+  - python-fastapi
+  - python-django
+  - golang-gin
+---
+
+# Redis
+
+## Overview
+
+Redis is an in-memory data structure store used as a cache, message broker, and database. This skill covers caching patterns, data structures, and common use cases.
+
+## Common Use Cases
+
+### Caching
+
+```typescript
+// Cache-aside pattern (most common)
+async function getUser(id: string): Promise<User> {
+  const cacheKey = `user:${id}`;
+
+  // 1. Check cache
+  const cached = await redis.get(cacheKey);
+  if (cached) return JSON.parse(cached);
+
+  // 2. Cache miss → fetch from DB
+  const user = await db.users.findById(id);
+  if (!user) throw new NotFoundError();
+
+  // 3. Populate cache with TTL
+  await redis.set(cacheKey, JSON.stringify(user), 'EX', 3600); // 1 hour
+
+  return user;
+}
+
+// Invalidate on mutation
+async function updateUser(id: string, data: UpdateUserDto): Promise<User> {
+  const user = await db.users.update(id, data);
+  await redis.del(`user:${id}`); // Invalidate cache
+  return user;
+}
+```
+
+### Sessions
+
+```typescript
+// Store session data with TTL
+await redis.set(`session:${sessionId}`, JSON.stringify({
+  userId: user.id,
+  role: user.role,
+  loginAt: Date.now(),
+}), 'EX', 86400); // 24 hours
+
+// Retrieve
+const session = JSON.parse(await redis.get(`session:${sessionId}`) || 'null');
+```
+
+### Rate Limiting
+
+```typescript
+// Sliding window rate limiter
+async function checkRateLimit(ip: string, limit: number, windowSec: number): Promise<boolean> {
+  const key = `ratelimit:${ip}`;
+  const current = await redis.incr(key);
+
+  if (current === 1) {
+    await redis.expire(key, windowSec);
+  }
+
+  return current <= limit;
+}
+```
+
+### Pub/Sub
+
+```typescript
+// Publisher
+await redis.publish('notifications', JSON.stringify({
+  userId: '123',
+  type: 'new_message',
+  payload: { from: 'Jane', text: 'Hello' },
+}));
+
+// Subscriber
+const sub = redis.duplicate();
+await sub.subscribe('notifications');
+sub.on('message', (channel, message) => {
+  const notification = JSON.parse(message);
+  sendToWebSocket(notification.userId, notification);
+});
+```
+
+## Data Structures
+
+```bash
+# Strings — basic key-value, counters
+SET user:123:name "John"
+INCR page:views:homepage
+
+# Hashes — object-like storage (memory efficient)
+HSET user:123 name "John" email "john@example.com" role "admin"
+HGET user:123 email
+
+# Lists — queues, recent items
+LPUSH queue:emails '{"to":"john@..."}'
+RPOP queue:emails
+
+# Sets — unique collections, tags
+SADD post:456:tags "javascript" "react" "tutorial"
+SISMEMBER post:456:tags "react"
+
+# Sorted Sets — leaderboards, time-series
+ZADD leaderboard 1500 "player1" 2300 "player2"
+ZREVRANGE leaderboard 0 9 WITHSCORES  # Top 10
+```
+
+## Best Practices
+
+1. **Use key namespaces** — `entity:id:field` pattern (`user:123:profile`)
+2. **Always set TTL** — prevent unbounded memory growth; use `EX` or `EXPIREAT`
+3. **Use pipelines** — batch multiple commands in one round trip
+4. **Prefer hashes** for objects — more memory-efficient than separate string keys
+5. **Avoid large keys** — break large values into smaller structures or use Streams
+6. **Use Lua scripts** for atomic operations — `EVAL` guarantees atomicity
+7. **Monitor memory** — use `INFO memory` and set `maxmemory-policy` (e.g., `allkeys-lru`)
+
+## Gotchas
+
+- **No built-in persistence guarantees** — RDB snapshots + AOF help, but Redis is not a primary database
+- **Single-threaded** — long-running commands (KEYS *, large SORT) block all clients; use SCAN instead
+- **Pub/Sub is fire-and-forget** — messages are lost if no subscriber is listening; use Streams for durability
+- **Serialization overhead** — JSON.stringify/parse adds latency; consider MessagePack for large payloads
+- **Connection limits** — each subscriber needs its own connection; use connection pooling