@hivehub/rulebook 2.1.0 → 3.1.0

package/templates/skills/services/mongodb/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: "MongoDB"
+description: "Use MongoDB for document-based NoSQL storage with flexible schemas, horizontal scaling, and rich querying."
+version: "1.0.0"
+category: "services"
+author: "Rulebook"
+tags: ["services", "database"]
+dependencies: []
+conflicts: []
+---
+<!-- MONGODB:START -->
+# MongoDB Database Instructions
+
+**CRITICAL**: Use MongoDB for document-based NoSQL storage with flexible schemas, horizontal scaling, and rich querying.
+
+## Core Features
+
+### Connection
+```typescript
+// Using mongodb driver
+import { MongoClient } from 'mongodb'
+
+const client = new MongoClient(process.env.MONGODB_URI || 'mongodb://localhost:27017', {
+  maxPoolSize: 10,
+  minPoolSize: 2,
+  maxIdleTimeMS: 30000,
+  serverSelectionTimeoutMS: 5000,
+})
+
+await client.connect()
+const db = client.db(process.env.DB_NAME || 'myapp')
+
+// Using Mongoose
+import mongoose from 'mongoose'
+
+await mongoose.connect(process.env.MONGODB_URI, {
+  maxPoolSize: 10,
+  minPoolSize: 2,
+  bufferCommands: false,
+  bufferMaxEntries: 0,
+})
+```
+
+### Basic Operations
+```typescript
+// Insert
+const result = await db.collection('users').insertOne({
+  name: 'John Doe',
+  email: 'john@example.com',
+  createdAt: new Date(),
+})
+
+// Insert many
+await db.collection('users').insertMany([
+  { name: 'User 1', email: 'user1@example.com' },
+  { name: 'User 2', email: 'user2@example.com' },
+])
+
+// Find
+const user = await db.collection('users').findOne({ email: 'john@example.com' })
+const users = await db.collection('users').find({ active: true }).toArray()
+
+// Update
+await db.collection('users').updateOne(
+  { email: 'john@example.com' },
+  { $set: { name: 'Jane Doe', updatedAt: new Date() } }
+)
+
+// Update many
+await db.collection('users').updateMany(
+  { active: false },
+  { $set: { status: 'inactive' } }
+)
+
+// Delete
+await db.collection('users').deleteOne({ email: 'john@example.com' })
+await db.collection('users').deleteMany({ active: false })
+```
+
+### Advanced Queries
+```typescript
+// Aggregation pipeline
+const result = await db.collection('orders').aggregate([
+  { $match: { status: 'completed' } },
+  { $group: { _id: '$userId', total: { $sum: '$amount' } } },
+  { $sort: { total: -1 } },
+  { $limit: 10 },
+]).toArray()
+
+// Text search
+await db.collection('articles').createIndex({ title: 'text', content: 'text' })
+const results = await db.collection('articles').find({
+  $text: { $search: 'search term' },
+}).toArray()
+
+// Geospatial queries
+await db.collection('locations').createIndex({ location: '2dsphere' })
+const nearby = await db.collection('locations').find({
+  location: {
+    $near: {
+      $geometry: { type: 'Point', coordinates: [longitude, latitude] },
+      $maxDistance: 1000, // meters
+    },
+  },
+}).toArray()
+
+// Array operations
+await db.collection('users').find({
+  tags: { $in: ['javascript', 'typescript'] },
+})
+await db.collection('users').updateOne(
+  { email: 'john@example.com' },
+  { $push: { tags: 'new-tag' } }
+)
+```
+
+## Common Patterns
+
+### Mongoose Schemas
+```typescript
+import mongoose, { Schema } from 'mongoose'
+
+const userSchema = new Schema({
+  name: { type: String, required: true },
+  email: { type: String, required: true, unique: true, index: true },
+  age: { type: Number, min: 0, max: 120 },
+  tags: [String],
+  metadata: { type: Schema.Types.Mixed },
+  createdAt: { type: Date, default: Date.now },
+  updatedAt: { type: Date, default: Date.now },
+})
+
+userSchema.pre('save', function(next) {
+  this.updatedAt = new Date()
+  next()
+})
+
+const User = mongoose.model('User', userSchema)
+```
+
+### Transactions
+```typescript
+const session = client.startSession()
+try {
+  await session.withTransaction(async () => {
+    await db.collection('accounts').updateOne(
+      { userId: userId },
+      { $inc: { balance: -100 } },
+      { session }
+    )
+    
+    await db.collection('transactions').insertOne(
+      { userId, amount: -100, type: 'debit' },
+      { session }
+    )
+  })
+} finally {
+  await session.endSession()
+}
+```
+
+### Indexing
+```typescript
+// Create indexes
+await db.collection('users').createIndex({ email: 1 }, { unique: true })
+await db.collection('users').createIndex({ name: 1, email: 1 })
+await db.collection('users').createIndex({ createdAt: -1 })
+
+// Compound index
+await db.collection('posts').createIndex({ authorId: 1, createdAt: -1 })
+
+// TTL index (auto-delete after time)
+await db.collection('sessions').createIndex(
+  { createdAt: 1 },
+  { expireAfterSeconds: 3600 }
+)
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use connection pooling (10-20 connections)
+- Create indexes on frequently queried fields
+- Use transactions for multi-document operations
+- Use $set for updates (don't replace entire documents)
+- Use projection to limit returned fields
+- Use aggregation pipeline for complex queries
+- Enable replica sets for production
+- Use sharding for large datasets
+- Monitor slow queries
+- Use appropriate data types (ObjectId, Date, etc.)
+
+❌ **DON'T:**
+- Store large binary data (use GridFS)
+- Create too many indexes (affects write performance)
+- Use $where (slow, use aggregation instead)
+- Skip error handling
+- Hardcode connection strings
+- Ignore connection pool limits
+- Use nested arrays deeply (limit to 2-3 levels)
+- Skip validation
+- Ignore query performance
+- Store sensitive data without encryption
+
+## Configuration
+
+### Environment Variables
+```bash
+MONGODB_URI=mongodb://localhost:27017/myapp
+MONGODB_URI=mongodb://user:password@host:27017/database?authSource=admin
+MONGODB_URI=mongodb+srv://user:password@cluster.mongodb.net/database
+```
+
+### Docker Compose
+```yaml
+services:
+  mongodb:
+    image: mongo:7
+    ports:
+      - "27017:27017"
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: admin
+      MONGO_INITDB_ROOT_PASSWORD: securepassword
+      MONGO_INITDB_DATABASE: myapp
+    volumes:
+      - mongodb_data:/data/db
+    healthcheck:
+      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  mongodb_data:
+```
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use test database
+const testClient = new MongoClient('mongodb://localhost:27017/test_db')
+await testClient.connect()
+const testDb = testClient.db('test_db')
+
+// Clean up after tests
+afterEach(async () => {
+  await testDb.collection('users').deleteMany({})
+  await testDb.collection('posts').deleteMany({})
+})
+
+// Use transactions for test isolation
+beforeEach(async () => {
+  const session = testClient.startSession()
+  session.startTransaction()
+  // Store session for rollback
+})
+
+afterEach(async () => {
+  await session.abortTransaction()
+  await session.endSession()
+})
+```
+
+### Health Checks
+```typescript
+async function checkDatabaseHealth(): Promise<boolean> {
+  try {
+    await client.db('admin').command({ ping: 1 })
+    return true
+  } catch {
+    return false
+  }
+}
+```
+
+<!-- MONGODB:END -->
+

package/templates/skills/services/mysql/SKILL.md

@@ -0,0 +1,368 @@
+---
+name: "MySQL"
+description: "Use MySQL for relational data storage with high performance, replication, and wide ecosystem support."
+version: "1.0.0"
+category: "services"
+author: "Rulebook"
+tags: ["services", "database"]
+dependencies: []
+conflicts: []
+---
+<!-- MYSQL:START -->
+# MySQL Database Instructions
+
+**CRITICAL**: Use MySQL for relational data storage with high performance, replication, and wide ecosystem support.
+
+## Core Features
+
+### Connection
+```typescript
+// Using mysql2 (Node.js)
+import mysql from 'mysql2/promise'
+
+const pool = mysql.createPool({
+  host: process.env.DB_HOST,
+  port: parseInt(process.env.DB_PORT || '3306'),
+  database: process.env.DB_NAME,
+  user: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  waitForConnections: true,
+  connectionLimit: 10,
+  queueLimit: 0,
+  enableKeepAlive: true,
+  keepAliveInitialDelay: 0,
+})
+
+// Using Prisma
+import { PrismaClient } from '@prisma/client'
+const prisma = new PrismaClient()
+```
+
+### Basic Queries
+```typescript
+// SELECT
+const [rows] = await pool.execute('SELECT * FROM users WHERE id = ?', [userId])
+const users = rows as User[]
+
+// INSERT
+const [result] = await pool.execute(
+  'INSERT INTO users (name, email) VALUES (?, ?)',
+  ['John Doe', 'john@example.com']
+)
+const insertId = (result as any).insertId
+
+// UPDATE
+const [result] = await pool.execute(
+  'UPDATE users SET name = ? WHERE id = ?',
+  ['Jane Doe', userId]
+)
+const affectedRows = (result as any).affectedRows
+
+// DELETE
+const [result] = await pool.execute('DELETE FROM users WHERE id = ?', [userId])
+```
+
+### Transactions
+```typescript
+const connection = await pool.getConnection()
+try {
+  await connection.beginTransaction()
+  
+  await connection.execute('INSERT INTO accounts (user_id, balance) VALUES (?, ?)', [userId, 1000])
+  await connection.execute('INSERT INTO transactions (account_id, amount) VALUES (?, ?)', [accountId, 1000])
+  
+  await connection.commit()
+} catch (error) {
+  await connection.rollback()
+  throw error
+} finally {
+  connection.release()
+}
+```
+
+### Advanced Features
+```typescript
+// JSON queries (MySQL 5.7+)
+const [rows] = await pool.execute(
+  "SELECT * FROM products WHERE JSON_EXTRACT(metadata, '$.category') = ?",
+  ['electronics']
+)
+
+// Full-text search
+const [rows] = await pool.execute(
+  "SELECT * FROM articles WHERE MATCH(title, content) AGAINST(? IN NATURAL LANGUAGE MODE)",
+  ['search term']
+)
+
+// Window functions (MySQL 8.0+)
+const [rows] = await pool.execute(`
+  SELECT 
+    name,
+    salary,
+    ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) as rank
+  FROM employees
+`)
+
+// Common Table Expressions (CTE) (MySQL 8.0+)
+const [rows] = await pool.execute(`
+  WITH RECURSIVE cte AS (
+    SELECT id, name, parent_id FROM categories WHERE parent_id IS NULL
+    UNION ALL
+    SELECT c.id, c.name, c.parent_id FROM categories c
+    INNER JOIN cte ON c.parent_id = cte.id
+  )
+  SELECT * FROM cte
+`)
+```
+
+## Common Patterns
+
+### Connection Pooling
+```typescript
+// Reuse connection pool
+let pool: mysql.Pool | null = null
+
+export function getPool(): mysql.Pool {
+  if (!pool) {
+    pool = mysql.createPool({
+      // ... config
+    })
+    
+    pool.on('connection', (connection) => {
+      connection.query('SET SESSION sql_mode = "STRICT_TRANS_TABLES"')
+    })
+  }
+  return pool
+}
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  if (pool) {
+    await pool.end()
+  }
+  process.exit(0)
+})
+```
+
+### Prepared Statements
+```typescript
+// Always use parameterized queries (?) to prevent SQL injection
+// ❌ WRONG
+await pool.execute(`SELECT * FROM users WHERE email = '${email}'`)
+
+// ✅ CORRECT
+await pool.execute('SELECT * FROM users WHERE email = ?', [email])
+```
+
+### Error Handling
+```typescript
+try {
+  const [rows] = await pool.execute('SELECT * FROM users WHERE id = ?', [userId])
+  if ((rows as any[]).length === 0) {
+    throw new Error('User not found')
+  }
+  return rows[0]
+} catch (error: any) {
+  if (error.code === 'ER_DUP_ENTRY') {
+    throw new Error('Duplicate entry')
+  }
+  if (error.code === 'ER_NO_REFERENCED_ROW_2') {
+    throw new Error('Referenced record does not exist')
+  }
+  throw error
+}
+```
+
+### Migrations
+```typescript
+// Using db-migrate
+import { migrate } from 'db-migrate'
+
+await migrate({
+  config: {
+    dev: {
+      driver: 'mysql',
+      database: process.env.DB_NAME,
+      user: process.env.DB_USER,
+      password: process.env.DB_PASSWORD,
+      host: process.env.DB_HOST,
+    }
+  },
+  env: 'dev',
+})
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use connection pooling (10-20 connections typically)
+- Always use parameterized queries (? placeholders)
+- Use transactions for multi-step operations
+- Create indexes on frequently queried columns
+- Use EXPLAIN to optimize queries
+- Enable query caching for read-heavy workloads
+- Use InnoDB engine (ACID compliance)
+- Set appropriate charset (utf8mb4 for full Unicode)
+- Monitor slow query log
+- Use prepared statements for repeated queries
+
+❌ **DON'T:**
+- Use string concatenation for queries (SQL injection risk)
+- Create too many connections (exhaust pool)
+- Skip error handling
+- Ignore connection pool limits
+- Use SELECT * in production (specify columns)
+- Skip indexes on foreign keys
+- Hardcode connection strings
+- Use MyISAM engine (no transactions)
+- Ignore query performance
+- Use synchronous queries
+
+## Configuration
+
+### Environment Variables
+```bash
+DB_HOST=localhost
+DB_PORT=3306
+DB_NAME=myapp
+DB_USER=myuser
+DB_PASSWORD=securepassword
+DATABASE_URL=mysql://user:password@host:port/database
+```
+
+### Docker Compose
+```yaml
+services:
+  mysql:
+    image: mysql:8.0
+    environment:
+      MYSQL_DATABASE: myapp
+      MYSQL_USER: myuser
+      MYSQL_PASSWORD: securepassword
+      MYSQL_ROOT_PASSWORD: rootpassword
+    ports:
+      - "3306:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+    command: --default-authentication-plugin=mysql_native_password
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  mysql_data:
+```
+
+### Prisma Schema
+```prisma
+datasource db {
+  provider = "mysql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique @db.VarChar(255)
+  name      String?  @db.VarChar(255)
+  createdAt DateTime @default(now()) @db.Timestamp(6)
+  posts     Post[]
+}
+
+model Post {
+  id        Int      @id @default(autoincrement())
+  title     String   @db.VarChar(255)
+  content   String?  @db.Text
+  authorId  Int
+  author    User     @relation(fields: [authorId], references: [id])
+  createdAt DateTime @default(now()) @db.Timestamp(6)
+  
+  @@index([authorId, createdAt(sort: Desc)])
+}
+```
+
+## Performance Optimization
+
+### Indexing
+```sql
+-- Single column index
+CREATE INDEX idx_users_email ON users(email);
+
+-- Composite index
+CREATE INDEX idx_posts_author_created ON posts(author_id, created_at DESC);
+
+-- Full-text index
+CREATE FULLTEXT INDEX idx_articles_content ON articles(title, content);
+
+-- Prefix index (for long strings)
+CREATE INDEX idx_users_name_prefix ON users(name(10));
+```
+
+### Query Optimization
+```typescript
+// Use LIMIT for pagination
+const [rows] = await pool.execute(
+  'SELECT * FROM posts ORDER BY created_at DESC LIMIT ? OFFSET ?',
+  [limit, offset]
+)
+
+// Use EXISTS instead of COUNT
+const [rows] = await pool.execute(
+  'SELECT EXISTS(SELECT 1 FROM users WHERE email = ?) as exists',
+  [email]
+)
+
+// Use JOIN instead of subqueries when possible
+const [rows] = await pool.execute(`
+  SELECT u.*, COUNT(p.id) as post_count
+  FROM users u
+  LEFT JOIN posts p ON u.id = p.author_id
+  GROUP BY u.id
+`)
+```
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use test database
+const testPool = mysql.createPool({
+  database: 'myapp_test',
+  // ... config
+})
+
+// Clean up after tests
+afterEach(async () => {
+  await testPool.execute('SET FOREIGN_KEY_CHECKS = 0')
+  await testPool.execute('TRUNCATE TABLE users')
+  await testPool.execute('TRUNCATE TABLE posts')
+  await testPool.execute('SET FOREIGN_KEY_CHECKS = 1')
+})
+
+// Use transactions for test isolation
+beforeEach(async () => {
+  const connection = await testPool.getConnection()
+  await connection.beginTransaction()
+  // Store connection for rollback
+})
+
+afterEach(async () => {
+  // Rollback transaction
+})
+```
+
+### Health Checks
+```typescript
+async function checkDatabaseHealth(): Promise<boolean> {
+  try {
+    const [rows] = await pool.execute('SELECT 1 as health')
+    return (rows as any[]).length > 0
+  } catch {
+    return false
+  }
+}
+```
+
+<!-- MYSQL:END -->
+